view release on metacpan or  search on metacpan

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

Path to the deployment plan file. Overrides target, engine, and core
configuration values. Defaults to F<$top_dir/sqitch.plan>.

=back

=head1 Examples

Add a change to a project and be prompted for a note.

  sqitch add widgets

Add a change and specify the note.

  sqitch add sprockets --note 'Adds the sprockets table.'

Add a change that requires the C<users> change from earlier in the plan.

  sqitch add contacts --requires users -n 'Adds the contacts table'

Add a change that requires multiple changes, including the change named
C<extract> from a completely different Sqitch project named C<utilities>:

  sqitch add coffee -r users -r utilities:extract -n 'Mmmmm...coffee!'

Add a change that uses the C<createtable> templates to generate the scripts,
as well as variables to be used in that template (See
L<https://justatheory.com/2013/09/sqitch-templating/> for a custom template
tutorial):

  sqitch add corp_widgets --template createtable \
    -s schema=corp -s table=widgets \
    -s column=id -s type=SERIAL \
    -s column=name -s type=TEXT \
    -s column=quantity -s type=INTEGER \
    -n 'Add corp.widgets table.'

Add a change only to the plan used by the C<vertica> engine in a project:

  sqitch add --change logs vertica -n 'Adds the logs table to Vertica.'

Add a change to just two plans in a project, and generate the scripts only for
those plans:

  sqitch add -a coolfunctions sqlite.plan pg.plan -n 'Adds functions.'

=head1 Templates

Sqitch contains a very simple set of templates for generating the deploy,
revert, and verify scripts, and you can create more of your own. By default,
Sqitch uses system-wide templates installed in
F<$(prefix)/etc/sqitch/templates>; call C<sqitch --etc-path> to find out
where, exactly (e.g., C<$(sqitch --etc-path)/templates>). Individual templates
may be overridden on a user basis by copying templates to
F<~/.sqitch/templates> and making modifications. They may also be overridden
by using the C<--template-directory> or C<--template-name> options, as well as
the template-specific options.

=head2 Directory Layout

Sqitch looks for templates in the following directories, and in this order:

=over

=item * C<--template-directory> or C<add.template_directory>

=item * F<~/.sqitch/templates/>

=item * F<$(prefix)/etc/sqitch/templates>

=back

Each should consist of subdirectories named for the types of scripts to be
generated. These should include F<deploy>, F<revert>, and F<verify>, but you
can create any number of other directories to create additional scripts that
will end up in a directory of the same name.

Each directory should include one or more files ending in F<.tmpl>. The
main part of the file name can be anything, but by default Sqitch will
look for a file named for the database engine. Use the C<--template> option
to have Sqitch use a different file.

For example, say you have this directory structure:

  templates/deploy/pg.tmpl
  templates/deploy/create_table.tmpl
  templates/revert/pg.tmpl
  templates/revert/create_table.tmpl
  templates/test/pg.tmpl
  templates/verify/pg.tmpl
  templates/verify/create_table.tmpl

Assuming that you're using the PostgreSQL engine, the code for which is C<pg>,
when you add a new change like so:

  sqitch add schema -n 'Creates schema'

Sqitch will use the C<pg.tmpl> files to create the following files in the
top directory configured for the project (See L<sqitch-configuration> for
details).

  deploy/schema.sql
  revert/schema.sql
  test/schema.sql
  verify/schema.sql

If you want to use the C<create_table> templates, instead, use the
C<--template> option, like so:

  sqitch add user_table --template create_table -n 'Create user table'

Sqitch will use the C<create_table.tmpl> files to create the following files
in the top directory configured for the project (See L<sqitch-configuration>
for details).

  deploy/user_table.sql
  revert/user_table.sql
  verify/user_table.sql

Note that the C<test> file was not created, because no
F<test/create_table.tmpl> template file exists.