view release on metacpan or  search on metacpan

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

=head1 Name

sqitch-target - Manage target database configuration

=head1 Synopsis

  sqitch target
  sqitch target [-v | --verbose]
  sqitch target add <name> <uri> [-s <property>=<value> ...]
  sqitch target alter <name> [-s <property>=<value> ...]
  sqitch target remove <name>
  sqitch target rename <old> <new>
  sqitch target show <name> [...]

=head1 Description

Manage the set of databases ("targets") you deploy to. Each target may have a
number of properties:

=over

=item C<uri>

The L<database connection URI|URI::db> for the target. Required. Its format is:

  db:engine:[dbname]
  db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment]

Some examples:

=over

=item C<db:sqlite:widgets.db>

=item C<db:pg://dba@example.net/blanket>

=item C<db:mysql://db.example.com/>

=item C<db:firebird://localhost//tmp/test.fdb>

=item C<db:clickhouse://default@localhost/default?Driver=ClickHouse>

=back

Note that, as with any URI or URL, special characters must be
L<URL encoded|https://en.wikipedia.org/wiki/URL_encoding>. For example, when
a username contains a reserved character, such as the C<|> in C<ro|michelle>,
it must be percent-encoded as C<%7c>:

  db:pg://ro%7Cmichelle@examle.org/inventory

The rules are even more strict for query parameters, as often used by for
ODBC connections. For example, when using a
L<Snowflake identifier|https://docs.snowflake.com/en/sql-reference/identifiers-syntax#double-quoted-identifiers>
with special characters, such as a warehouse name with a C<.>, such as
C<sqitch.dev>, the identifier must be double-quoted --- and double quote are
reserved characters in URIs, so must be encoded as C<%22>.

  db:snowflake://example/flipr?Driver=Snowflake;warehouse=%22sqitch.dev%22

See L<URL encoding|https://en.wikipedia.org/wiki/URL_encoding> for details.
and the L<DB URI Draft|https://github.com/libwww-perl/uri-db> for in-depth
information on database URIs in general.

=item C<registry>

The name of the registry schema or database. The default is C<sqitch>.

=item C<client>

The command-line client to use. If not specified, each engine looks in the OS
Path for an appropriate client.

=item C<top_dir>

The path to the top directory for the target. This directory generally
contains the plan file and subdirectories for deploy, revert, and verify
scripts, as well as reworked instances of those scripts. The default is F<.>,
the current directory.

=item C<plan_file>

The plan file to use for this target. The default is C<$top_dir/sqitch.plan>.

=item C<deploy_dir>

The path to the deploy directory for the target. This directory contains all
of the deploy scripts referenced by changes in the C<plan_file>. The default
is C<$top_dir/deploy>.

=item C<revert_dir>

The path to the revert directory for the target. This directory contains all
of the revert scripts referenced by changes in the C<plan_file>. The default
is C<$top_dir/revert>.

=item C<verify_dir>

The path to the verify directory for the target. This directory contains all
of the verify scripts referenced by changes in the C<plan_file>. The default
is C<$top_dir/verify>.

=item C<reworked_dir>

The path to the reworked directory for the target. This directory contains all
subdirectories for all reworked scripts referenced by changes in the
C<plan_file>. The default is C<$top_dir>.