=encoding UTF-8

=head1 Name

sqitch-passwords - Guide to using database passwords with Sqitch

=head1 Description

You may have noticed that Sqitch has no C<--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 three recommended approaches, in order from most-
to least-recommended:

=over

=item 1. Avoid using a password at all

=item 2. Use a database engine-specific password file

=item 3. Use the C<$SQITCH_PASSWORD> environment variable

=item 4. Include the password in the deploy target URI

=back

Each is covered in detail in the sections below.

=head1 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:

=over

=item PostgreSQL

PostgreSQL supports a number of
L<authentication methods|http://www.postgresql.org/docs/current/static/auth-methods.html>,
including the passwordless L<SSL certificate|http://www.postgresql.org/docs/current/static/auth-methods.html#AUTH-CERT>, L<GSSAPI|http://www.postgresql.org/docs/current/static/auth-methods.html#GSSAPI-AUTH>, and, for local connections,
L<peer authentication|http://www.postgresql.org/docs/current/static/auth-methods.html#AUTH-PEER>.

=item MySQL

MySQL supports a number of
L<authentication methods|http://dev.mysql.com/doc/internals/en/authentication-method.html>,
plus L<SSL authentication|http://dev.mysql.com/doc/internals/en/ssl.html>.

=item Oracle

Oracle supports a number of
L<authentication methods|http://docs.oracle.com/cd/B19306_01/network.102/b14266/authmeth.htm#BABCGGEB>,
including
L<SSL authentication|http://docs.oracle.com/cd/B19306_01/network.102/b14266/authmeth.htm#i1009722>,
L<third-party authentication|http://docs.oracle.com/cd/B19306_01/network.102/b14266/authmeth.htm#i1009853>,
and, for local connections,
L<OS authentication|http://docs.oracle.com/cd/B19306_01/network.102/b14266/authmeth.htm#i1007520>.

=item Vertica

Vertica supports a number of
L<authentication methods|http://my.vertica.com/docs/7.1.x/HTML/index.htm#Authoring/AdministratorsGuide/Security/ClientAuth/SupportedClientAuthenticationMethods.htm%3FTocPath%3DAdministrator's%20Guide%7CImplementing%20Security%7CClient%20Authentication%7C_____3>
including the passwordless L<TLS authentication|http://my.vertica.com/docs/7.1.x/HTML/index.htm#Authoring/AdministratorsGuide/Security/ClientAuth/ConfiguringTLSAuthentication.htm%3FTocPath%3DAdministrator's%20Guide%7CImplementing%20Security%7CClient%20Authentication%7CConfiguring%20TLS%C2%A0Authentication%7C_____0>,
L<GSS authentication|http://my.vertica.com/docs/7.1.x/HTML/index.htm#Authoring/AdministratorsGuide/Security/ClientAuth/Kerberos/ImplementingKerberosAuthentication.htm%3FTocPath%3DAdministrator's%20Guide%7CImplementing%20Security%7CClient%20Authentication%7CConfiguring%20Kerberos%20Authentication%7C_____0>,
and, for local connections,
L<ident authentication|http://my.vertica.com/docs/7.1.x/HTML/index.htm#Authoring/AdministratorsGuide/Security/ClientAuth/ConfiguringIdentAuthentication.htm%3FTocPath%3DAdministrator's%20Guide%7CImplementing%20Security%7CClient%20Authentication%7CConfiguring%20Ident%20Authentication%7C_____0>.

=item Firebird

Firebird supports passwordless authentication only via
L<trusted authentication|http://www.firebirdsql.org/manual/qsg2-config.html>
for local connections.

=back

=head1 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:

=over

=item PostgreSQL

PostgreSQL will use a
L<F<.pgpass> file|http://www.postgresql.org/docs/current/static/libpq-pgpass.html> in the
user's home directory to or referenced by the C<$PGPASSFILE> environment
variable. This file must limit access only to the current user (C<0600>) and
contains lines specify authentication rules as follows:

  hostname:port:database:username:password

=item MySQL

For MySQL, passwords can be specified in the
L<F</etc/my.cnf> and F<~/.my.cnf> files|http://dev.mysql.com/doc/refman/5.1/en/password-security-user.html#idm139947650158560>.
These files must limit access only to the current user (C<0600>) and. Sqitch
will look for a password under the C<[client]> and C<[mysql]> sections, in that
order.

=item Oracle

Oracle supports
C<password file|http://docs.oracle.com/cd/B28359_01/server.111/b28310/dba007.htm#ADMIN10241>
created with the C<ORAPWD> utility to authenticate C<SYSDBA> and C<SYSOPER>
users, but B<Sqitch is unable to take advantage of this functionality.> Neither can
one L<embed a username and password|http://stackoverflow.com/q/7183513/79202>
into a
L<F<tnsnames.ora>|http://docs.oracle.com/cd/B28359_01/network.111/b28317/tnsnames.htm#NETRF007>
file.

=item Vertica

Vertica does not currently support a password file.

=item Firebird

Firebird does not currently support a password file.

=back

=head1 Use C<$SQITCH_PASSWORD>

The C<$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 C<ps>.

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

=over

=item PostgreSQL

C<$PGPASSWORD>

=item MySQL

C<$MYSQL_PWD>

=item Vertica

C<$VSQL_PASSWORD>

=item Firebird

C<$ISC_PASSWORD>

=back

=head1 Use Target URIs

Passwords may also be specified in L<target URIs|sqitch-target/Description>.
This is not generally recommended, since such URIs are either specified via
the command-line (and therefore visible in C<ps> and your shell history) or
stored in the L<configuration|sqitch-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 L<sqitch-targets> and C<sqitch-configuration> for details  on target
configuration.

=head1 See Also

=over

=item * L<sqitch-environment>

=item * L<sqitch-configuration>

=item * L<sqitch-target>

=back

=head1 Sqitch

Part of the L<sqitch> suite.