sqitch-authentication - Guide to using database authentication credentials with Sqitch


For database engines that require authentication, Sqitch supports a number of credential-specification options, and searches for them in a specific sequence. These searches are performed in two parts: a search for a username and a search for a password.


Sqitch searches for usernames sequentially, using the first value it finds. Any of these approaches may be used to specify a username, in this order:

Naturally, this last option varies by database engine. The details are as follows:


You may have noticed that Sqitch has no --password option. This is intentional. It’s generally not a great idea to specify a password on the command-line: from there, it gets logged to your command history and is easy to extract by anyone with access to your system. So you might wonder how to specify passwords so that Sqitch an successfully deploy to databases that require passwords. There are four approaches, in order from most- to least-recommended:

Each is covered in detail in the sections below.

Don’t use Passwords

Of course, the best way to protect your passwords is not to use them at all. If your database engine is able to do passwordless authentication, it’s worth taking the time to make it work, especially on your production database systems. Some examples:

Use a Password File

If you must use password authentication with your database server, you may be able to use a protected password file. This is file with access limited only to the current user that the server client library can read in. As such, the format is specified by the database vendor, and not all database servers offer the feature. Here’s how the database engines supported by Sqitch shake out:


The $SQITCH_PASSWORD environment variable can be used to specify the password for any supported database engine. However use of this environment variable is not recommended for security reasons, as some operating systems allow non-root users to see process environment variables via ps.

The behavior of $SQITCH_PASSWORD is consistent across all supported engines, as is the complementary $SQITCH_USERNAME environment variable. Some database engines support their own password environment variables, which you may wish to use instead. However, their behaviors may not be consistent:

Use Target URIs

Passwords may also be specified in target URIs. This is not generally recommended, since such URIs are either specified via the command-line (and therefore visible in ps and your shell history) or stored in the configuration, the project instance of which is generally pushed to your source code repository. But it’s provided here as an absolute last resort (and because web URLs support it, though it’s heavily frowned upon there, too).

Such URIs can either be specified on the command-line:

sqitch deploy db:pg://fred:s3cr3t@db.example.com/widgets

Or stored as named targets in the project configuration file:

sqitch target add wigets db:pg://fred:s3cr3t@db.example.com/widgets

After which the target is available by its name:

sqitch deploy widgets

See sqitch-targets and sqitch-configuration for details on target configuration.

See Also


Part of the sqitch suite.