view release on metacpan or  search on metacpan

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

More interesting, perhaps, is the C<client> setting, which defaults to the
appropriate engine-specific client name appropriate for your OS. In this
example, sqitch will assume it can find F<psql> in your path.

=head1 Global Configuration

But sometimes that's not the case. Let's say that the C<psql> client on your
system is not in the path, but instead in F</usr/local/pgsql/bin/psql>. You
could set its location right here in the project configuration file, but that
won't do if you end up distributing the project to other users who might have
their client somewhere else. For that use case, the default path-specific
value is probably best.

A better idea is to tell Sqitch where to find F<psql> for I<all> of your
projects. Use the L<C<config>|sqitch-config> command's C<--user> option to set
that configuration for yourself:

  > sqitch config --user engine.pg.client /usr/local/pgsql/bin/psql

This won't change the project configuration file at all, but add the value to
F<~/.sqitch/sqitch.conf>, which is your personal cross-project Sqitch
configuration. In other words, it sets the PostgreSQL client for all Sqitch
projects you manage on this host. In fact, it can be a good idea to configure
clients not in the path first thing whenever you start working on a new host:

  > sqitch config --user user.name 'Marge N. O’Vera'
  > sqitch config --user user.email 'marge@example.com'
  > sqitch config --user engine.pg.client /usr/local/pgsql/bin/psql
  > sqitch config --user engine.mysql.client /usr/local/mysql/bin/mysql
  > sqitch config --user engine.sqlite.client /sbin/sqlite3

If you'd like to make the configuration global to all accounts on your host,
use the C<--system> option, instead:

  > sudo sqitch config --system engine.pg.client /usr/local/pgsql/bin/psql
  > sudo sqitch config --system engine.mysql.client /usr/local/mysql/bin/mysql
  > sudo sqitch config --system engine.sqlite.client /sbin/sqlite3

That will put the values into the global Sqitch configuration file, which is
in C<`sqitch --etc-path`/sqitch.conf>.

=head1 Engine Configuration

So you've got the widgets project well developed, and now you've been asked to
port it to SQLite. Fundamentally, that means porting all of your deploy,
revert, and verify scripts. The simplest way to organize files for this
configuration is with top-level directories for each engine. First, let's move
the existing PostgreSQL stuff to a subdirectory.

  > mkdir pg
  > mv deploy revert verify sqitch.plan pg
  > ls  pg
  deploy/ revert/ sqitch.plan verify/

Now we need to tell Sqitch where things are. To create an engine-specific
configuration, use the L<C<engine>|sqitch-engine> command's C<add> action:

  sqitch engine add pg --top-dir pg

The C<add> action adds the C<pg> engine to the configuration, setting the top
directory to our newly-created C<pg> directory. The configuration looks like
this (with comments removed for clarity):

  [core]
    engine = pg
  [engine "pg"]
    target = db:pg:
    top_dir = pg

Curious about all the other settings for the engine? Let C<sqitch engine show>
show you:

  > sqitch engine show pg
  * pg
      Target:        db:pg:
      Registry:      sqitch
      Client:        psql
      Top Directory: pg
      Plan File:     pg/sqitch.plan
      Extension:     sql
      Script Directories:
        Deploy:      pg/deploy
        Revert:      pg/revert
        Verify:      pg/verify
      Reworked Script Directories:
        Reworked:    pg
        Deploy:      pg/deploy
        Revert:      pg/revert
        Verify:      pg/verify
      No Variables

The C<show> action nicely presents the result of the fully-evaluated
configuration, even though only the top directory and client have been set.
Nice, right?

Now, to add the SQLite support. There are two basic ways to go about it. We'll
start with the more obvious one.

=head2 Separate Plans

The first approach is to create an entirely independent SQLite project with
its own plan and scripts. This is I<almost> like starting from scratch: just
create a new directory and add the Sqitch engine using it for its top
directory: add initialize it as a new Sqitch project:

  > sqitch engine add sqlite --top-dir sqlite
  Created sqlite/
  Created sqlite/sqitch.plan
  Created sqlite/deploy/
  Created sqlite/revert/
  Created sqlite/verify/

Note the creation of a new F<sqlite/sqitch.conf> file. It will have copied the
project name and URI from the existing plan file. The SQLite configuration is
now added to the configuration file:

  > sqitch engine show sqlite
  * sqlite
      Target:        db:sqlite:
      Registry:      sqitch
      Client:        sqlite3

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

  pg/deploy/utility/func_update_connection@v2.11.0.sql
  pg/revert/extensions@v2.9.0.sql
  pg/revert/jobs/func_enabler@v2.6.1.sql
  pg/revert/stem/func_check_all_widgets@v2.11.0.sql
  pg/revert/stem/func_check_all_widgets@v2.12.2.sql
  pg/revert/stem/func_check_all_widgets@v2.12.3.sql
  pg/revert/crank/func_update_jobs@v2.12.0.sql
  pg/revert/crank/func_update_jobs@v2.8.0.sql
  pg/revert/utility/func_get_sleepercell@v2.9.0.sql
  pg/revert/utility/func_update_connection@v2.10.0.sql
  pg/revert/utility/func_update_connection@v2.10.1.sql
  pg/revert/utility/func_update_connection@v2.11.0.sql
  pg/verify/extensions@v2.9.0.sql
  pg/verify/jobs/func_enabler@v2.6.1.sql
  pg/verify/stem/func_check_all_widgets@v2.11.0.sql
  pg/verify/stem/func_check_all_widgets@v2.12.2.sql
  pg/verify/stem/func_check_all_widgets@v2.12.3.sql
  pg/verify/crank/func_update_jobs@v2.12.0.sql
  pg/verify/crank/func_update_jobs@v2.8.0.sql
  pg/verify/utility/func_get_sleepercell@v2.9.0.sql
  pg/verify/utility/func_update_connection@v2.10.0.sql
  pg/verify/utility/func_update_connection@v2.10.1.sql
  pg/verify/utility/func_update_connection@v2.11.0.sql

Ugh. Wouldn't it be nice to move them out of the way? Of course it would! So
let's do that. We want all of the PostgreSQL engine's reworked scripts all to
go into to a new directory named "reworked", so tell Sqitch where to find
them:

  > sqitch engine alter pg --dir reworked=pg/reworked
  Created pg/reworked/deploy/
  Created pg/reworked/revert/
  Created pg/reworked/verify/

Great, it created the new directories. Note that if you wanted the directories
to have different names or locations, you can use the C<reworked_deploy>,
C<reworked_revert>, and C<reworked_verify> options.

Now all we have to do is move the files:

  cd pg
  for file in `find . -name '*@*'`
  do
      mkdir -p reworked/`dirname $file`
      mv $file reworked/`dirname $file`
  done
  cd ..

Now all the reworked deploy files are in F<pg/reworked/deploy>, the reworked
revert files are in F<pg/reworked/revert>, and the reworked verify files are
in F<pg/reworked/verify>. And you're good to go! From here on in Sqitch always
knows to find the reworked scripts when doing a L<deploy|sqitch-deploy>,
L<revert|sqitch-revert>, or L<bundle|sqitch-bundle>. And meanwhile, they're
tucked out of the way, less likely to break your brain or your IDE.

=head1 Other Options

You can see by the output of the L<C<init>|sqitch-init>,
L<C<engine>|sqitch-engine>, and L<C<target>|sqitch-target> commands that there
are quite a few other properties that can be set on a per-engine or per-target
database. To determine the value of each, Sqitch looks at a combination of
command-line options and configuration variables. Here's a complete list,
including specification of their values and how to set them.

=over

=item C<target>

The target database. May be a L<database URI|https://github.com/libwww-perl/uri-db> or
a named target managed by the L<C<target>|sqitch-target> commands. On each run,
its value will be determined by examining each of the following in turn:

=over

=item Command target argument or option

  sqitch deploy $target
  sqitch revert --target $target

=item C<$SQITCH_TARGET> environment variable

  env SQITCH_TARGET=$target sqitch deploy
  env SQITCH_TARGET=$target sqitch revert

=item C<engine.$engine.target>

  sqitch init $project --engine $engine --target $target
  sqitch engine add $engine --target $target
  sqitch engine alter $engine --target target

=item C<core.target>

  sqitch config core.target $target

=back

=item C<uri>

The L<database URI|https://github.com/libwww-perl/uri-db> to which to connect. May
only be specified as a target argument or via a named target:

=over

=item Command target argument or option

  sqitch deploy $uri
  sqitch revert --target $uri

=item C<$SQITCH_TARGET> environment variable

  env SQITCH_TARGET=$uri sqitch deploy
  env SQITCH_TARGET=$uri sqitch revert

=item C<target.$target.uri>

  sqitch init $project --engine $engine --target $uri
  sqitch target add $target --uri $uri
  sqitch target alter $target --uri $uri

=back