view release on metacpan or  search on metacpan

lib/sqitch-authentication.pod  view on Meta::CPAN

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.

=head1 Usernames

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:

=over

=item 1. In the C<$SQITCH_USERNAME> environment variable

=item 2. Via the C<--db-username> option

=item 3. In the deploy target URI; this is the preferred option

=item 4. In an engine-specific environment variable or configuration

=back

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

=over

=item PostgreSQL, YugabyteDB, CockroachDB

The Postgres, Yugabyte, and Cockroach engines use the C<PGUSER> environment
variable, if set. Otherwise, it uses the system username.

=item MySQL

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

=item Oracle

Oracle provides no default to search for a username.

=item Vertica

The Vertica engine uses the C<VSQL_USER> environment variable, if set.
Otherwise, it uses the system username.

=item Firebird

The Firebird engine uses the C<ISC_USER> environment variable, if set.

=item Exasol

Exasol provides no default to search for a username.

=item Snowflake

The Snowflake engine uses the C<SNOWSQL_USER> environment variable, if set.
Next, it looks in the
L<F<~/.snowsql/config> file|https://docs.snowflake.com/en/user-guide/snowsql-start.html#snowsql-config-file>
and use the default C<connections.username> value. Otherwise, it uses the
system username.

=item ClickHouse

The ClickHouse engine uses the C<CLICKHOUSE_USER> environment variable, if set.

=back

=head1 Passwords

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 four 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.

=head2 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|https://www.postgresql.org/docs/current/static/auth-methods.html>,
including the passwordless L<SSL certificate|https://www.postgresql.org/docs/current/static/auth-methods.html#AUTH-CERT>, L<GSSAPI|https://www.postgresql.org/docs/current/static/auth-methods.html#GSSAPI-AUTH>, and, for local connections,
L<peer authentication|https://www.postgresql.org/docs/current/static/auth-methods.html#AUTH-PEER>.

=item MySQL

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

=item Oracle

Oracle supports a number of
L<authentication methods|https://docs.oracle.com/cd/B19306_01/network.102/b14266/authmeth.htm#BABCGGEB>,