view release on metacpan or  search on metacpan

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

template directory for templates, it uses this name to find them in subdirectories
named for the various types of scripts, including:

=over

=item C<deploy/$name.tmpl>

=item C<revert/$name.tmpl>

=item C<verify/$name.tmpl>

=back

Any templates found with the same name in additional subdirectories will also
be evaluated.

This option allows one to define templates for specific tasks, such as
creating a table, and then use them for changes that perform those tasks.
Defaults to the name of the database engine (C<pg>, C<sqlite>, C<mysql>,
C<oracle>, C<firebird>, C<vertica>, C<exasol>, C<snowflake>, C<cockroach>, or
C<clickhouse>).

=item C<--use script=template>

Specify the path to a template for a specific type of script. Defaults to the
individual templates and using C<--template-name>, found in
C<--template-directory> and the configuration template directories.

=item C<--with>

=item C<--without>

Specify a type of template to generate or not generate.

=item C<-e>

=item C<--edit>

=item C<--open-editor>

Open the generated change scripts in an editor.

=item C<--no-edit>

=item C<--no-open-editor>

Do not open the change scripts in an editor. Useful when L<C<add.open_editor>>
is true.

=item C<--plan-file>

=item C<-f>

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>