.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "sqitch-add 3pm"
.TH sqitch-add 3pm 2024-02-08 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH Name
.IX Header "Name"
sqitch-add \- Add a database change to plans
.SH Synopsis
.IX Header "Synopsis"
.Vb 4
\& sqitch add widgets [options
\& sqitch add blankets \-\-all
\& sqitch add \-\-change sprockets pg sql
\& sqitch add slinkies \-\-require sprockets \-\-set schema=industry
.Ve
.SH Description
.IX Header "Description"
This command adds a database change to one or more plans. This will result in
the creation of script files in the deploy, revert, and verify directories,
and possibly others. The content of these files is determined by the
evaluation of templates. By default, system templates in
\&\fI$(prefix)/etc/sqitch/templates\fR are used. These can be overridden by a
single user by creating templates in \fI~/.sqitch/templates/\fR See "Templates"
for details.
.PP
The paths and extensions of the generated scripts depend on the configuration
of Sqitch targets, engines, and the core. See sqitch-configuration for
details.
.PP
Note that the name of the new change must adhere to the rules as defined in
sqitchchanges.
.PP
By default, the \f(CW\*(C`add\*(C'\fR command will add the change to the default plan and the
scripts to any top directories for that plan, as defined by the core
configuration and command-line options. This works well for projects in which
there is a single plan with separate top directories for each engine, for
example. Pass the \f(CW\*(C`\-\-all\*(C'\fR option to have it iterate over all known plans and
top directories (as specified for engines and targets) and add the change to
them all.
.PP
To specify which plans and top directories to which the change and its scripts
will be added, pass the target, engine, or plan file names as arguments. Use
\&\f(CW\*(C`\-\-change\*(C'\fR to disambiguate the tag and change names from the other parameters
if necessary (or preferable). See "Examples" for examples.
.SH Options
.IX Header "Options"
.ie n .IP """\-c""" 4
.el .IP \f(CW\-c\fR 4
.IX Item "-c"
.PD 0
.ie n .IP """\-\-change""" 4
.el .IP \f(CW\-\-change\fR 4
.IX Item "--change"
.ie n .IP """\-\-change\-name""" 4
.el .IP \f(CW\-\-change\-name\fR 4
.IX Item "--change-name"
.PD
The name of the change to add. The name can be specified with or without this
option, but the option can be useful for disambiguating the change name from
other arguments.
.ie n .IP """\-r""" 4
.el .IP \f(CW\-r\fR 4
.IX Item "-r"
.PD 0
.ie n .IP """\-\-requires""" 4
.el .IP \f(CW\-\-requires\fR 4
.IX Item "--requires"
.PD
Name of a change that is required by the new change. May be specified multiple
times. See sqitchchanges for the various ways in which changes can be
specified.
.ie n .IP """\-x""" 4
.el .IP \f(CW\-x\fR 4
.IX Item "-x"
.PD 0
.ie n .IP """\-\-conflicts""" 4
.el .IP \f(CW\-\-conflicts\fR 4
.IX Item "--conflicts"
.PD
Name of a change that conflicts with the new change. May be specified multiple
times. See sqitchchanges for the various ways in which changes can be
specified.
.ie n .IP """\-a""" 4
.el .IP \f(CW\-a\fR 4
.IX Item "-a"
.PD 0
.ie n .IP """\-\-all""" 4
.el .IP \f(CW\-\-all\fR 4
.IX Item "--all"
.PD
Add the change to all plans in the project. Cannot be mixed with target,
engine, or plan file name arguments; doing so will result in an error. Useful
for multi-plan projects in which changes should be kept in sync. Overrides the
value of the \f(CW\*(C`add.all\*(C'\fR configuration; use \f(CW\*(C`\-\-no\-all\*(C'\fR to override a true
\&\f(CW\*(C`add.all\*(C'\fR configuration.
.ie n .IP """\-n""" 4
.el .IP \f(CW\-n\fR 4
.IX Item "-n"
.PD 0
.ie n .IP """\-\-note""" 4
.el .IP \f(CW\-\-note\fR 4
.IX Item "--note"
.PD
A brief note describing the purpose of the change. The note will be attached
to the change as a comment. Multiple invocations will be concatenated together
as separate paragraphs.
.Sp
For you Git folks out there, \f(CW\*(C`\-m\*(C'\fR also works.
.ie n .IP """\-s""" 4
.el .IP \f(CW\-s\fR 4
.IX Item "-s"
.PD 0
.ie n .IP """\-\-set""" 4
.el .IP \f(CW\-\-set\fR 4
.IX Item "--set"
.PD
Set a variable name and value for use in the templates. The format must be
\&\f(CW\*(C`name=value\*(C'\fR, e.g., \f(CW\*(C`\-\-set comment=\*(AqThis one is for you, babe.\*(Aq\*(C'\fR.
.ie n .IP """\-\-template\-directory""" 4
.el .IP \f(CW\-\-template\-directory\fR 4
.IX Item "--template-directory"
Location to look for the templates. If none is specified, \f(CW\*(C`add\*(C'\fR will
first look in \fI~/.sqitch/templates/\fR for each template, and fall back on
\&\fI$(prefix)/etc/sqitch/templates\fR.
.ie n .IP """\-t""" 4
.el .IP \f(CW\-t\fR 4
.IX Item "-t"
.PD 0
.ie n .IP """\-\-template""" 4
.el .IP \f(CW\-\-template\fR 4
.IX Item "--template"
.ie n .IP """\-\-template\-name""" 4
.el .IP \f(CW\-\-template\-name\fR 4
.IX Item "--template-name"
.PD
Name of the templates to use for the scripts. When Sqitch searches the
template directory for templates, it uses this name to find them in subdirectories
named for the various types of scripts, including:
.RS 4
.ie n .IP """deploy/$name.tmpl""" 4
.el .IP \f(CWdeploy/$name.tmpl\fR 4
.IX Item "deploy/$name.tmpl"
.PD 0
.ie n .IP """revert/$name.tmpl""" 4
.el .IP \f(CWrevert/$name.tmpl\fR 4
.IX Item "revert/$name.tmpl"
.ie n .IP """verify/$name.tmpl""" 4
.el .IP \f(CWverify/$name.tmpl\fR 4
.IX Item "verify/$name.tmpl"
.RE
.RS 4
.PD
.Sp
Any templates found with the same name in additional subdirectories will also
be evaluated.
.Sp
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 (\f(CW\*(C`pg\*(C'\fR, \f(CW\*(C`sqlite\*(C'\fR, \f(CW\*(C`mysql\*(C'\fR,
\&\f(CW\*(C`oracle\*(C'\fR, \f(CW\*(C`firebird\*(C'\fR, \f(CW\*(C`vertica\*(C'\fR, \f(CW\*(C`exasol\*(C'\fR, or \f(CW\*(C`snowflake\*(C'\fR).
.RE
.ie n .IP """\-\-use script=template""" 4
.el .IP "\f(CW\-\-use script=template\fR" 4
.IX Item "--use script=template"
Specify the path to a template for a specific type of script. Defaults to the
individual templates and using \f(CW\*(C`\-\-template\-name\*(C'\fR, found in
\&\f(CW\*(C`\-\-template\-directory\*(C'\fR and the configuration template directories.
.ie n .IP """\-\-with""" 4
.el .IP \f(CW\-\-with\fR 4
.IX Item "--with"
.PD 0
.ie n .IP """\-\-without""" 4
.el .IP \f(CW\-\-without\fR 4
.IX Item "--without"
.PD
Specify a type of template to generate or not generate.
.ie n .IP """\-e""" 4
.el .IP \f(CW\-e\fR 4
.IX Item "-e"
.PD 0
.ie n .IP """\-\-edit""" 4
.el .IP \f(CW\-\-edit\fR 4
.IX Item "--edit"
.ie n .IP """\-\-open\-editor""" 4
.el .IP \f(CW\-\-open\-editor\fR 4
.IX Item "--open-editor"
.PD
Open the generated change scripts in an editor.
.ie n .IP """\-\-no\-edit""" 4
.el .IP \f(CW\-\-no\-edit\fR 4
.IX Item "--no-edit"
.PD 0
.ie n .IP """\-\-no\-open\-editor""" 4
.el .IP \f(CW\-\-no\-open\-editor\fR 4
.IX Item "--no-open-editor"
.PD
Do not open the change scripts in an editor. Useful when \f(CW\*(C`add.open_editor\*(C'\fR
is true.
.ie n .IP """\-\-plan\-file""" 4
.el .IP \f(CW\-\-plan\-file\fR 4
.IX Item "--plan-file"
.PD 0
.ie n .IP """\-f""" 4
.el .IP \f(CW\-f\fR 4
.IX Item "-f"
.PD
Path to the deployment plan file. Overrides target, engine, and core
configuration values. Defaults to \fR\f(CI$top_dir\fR\fI/sqitch.plan\fR.
.SH Examples
.IX Header "Examples"
Add a change to a project and be prompted for a note.
.PP
.Vb 1
\& sqitch add widgets
.Ve
.PP
Add a change and specify the note.
.PP
.Vb 1
\& sqitch add sprockets \-\-note \*(AqAdds the sprockets table.\*(Aq
.Ve
.PP
Add a change that requires the \f(CW\*(C`users\*(C'\fR change from earlier in the plan.
.PP
.Vb 1
\& sqitch add contacts \-\-requires users \-n \*(AqAdds the contacts table\*(Aq
.Ve
.PP
Add a change that requires multiple changes, including the change named
\&\f(CW\*(C`extract\*(C'\fR from a completely different Sqitch project named \f(CW\*(C`utilities\*(C'\fR:
.PP
.Vb 1
\& sqitch add coffee \-r users \-r utilities:extract \-n \*(AqMmmmm...coffee!\*(Aq
.Ve
.PP
Add a change that uses the \f(CW\*(C`createtable\*(C'\fR templates to generate the scripts,
as well as variables to be used in that template (See
for a custom template
tutorial):
.PP
.Vb 6
\& sqitch add corp_widgets \-\-template createtable \e
\& \-s schema=corp \-s table=widgets \e
\& \-s column=id \-s type=SERIAL \e
\& \-s column=name \-s type=TEXT \e
\& \-s column=quantity \-s type=INTEGER \e
\& \-n \*(AqAdd corp.widgets table.\*(Aq
.Ve
.PP
Add a change only to the plan used by the \f(CW\*(C`vertica\*(C'\fR engine in a project:
.PP
.Vb 1
\& sqitch add \-\-change logs vertica \-n \*(AqAdds the logs table to Vertica.\*(Aq
.Ve
.PP
Add a change to just two plans in a project, and generate the scripts only for
those plans:
.PP
.Vb 1
\& sqitch add \-a coolfunctions sqlite.plan pg.plan \-n \*(AqAdds functions.\*(Aq
.Ve
.SH Templates
.IX Header "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
\&\fI$(prefix)/etc/sqitch/templates\fR; call \f(CW\*(C`sqitch \-\-etc\-path\*(C'\fR to find out
where, exactly (e.g., \f(CW\*(C`$(sqitch \-\-etc\-path)/templates\*(C'\fR). Individual templates
may be overridden on a user basis by copying templates to
\&\fI~/.sqitch/templates\fR and making modifications. They may also be overridden
by using the \f(CW\*(C`\-\-template\-directory\*(C'\fR or \f(CW\*(C`\-\-template\-name\*(C'\fR options, as well as
the template-specific options.
.SS "Directory Layout"
.IX Subsection "Directory Layout"
Sqitch looks for templates in the following directories, and in this order:
.IP \(bu 4
\&\f(CW\*(C`\-\-template\-directory\*(C'\fR or \f(CW\*(C`add.template_directory\*(C'\fR
.IP \(bu 4
\&\fI~/.sqitch/templates/\fR
.IP \(bu 4
\&\fI$(prefix)/etc/sqitch/templates\fR
.PP
Each should consist of subdirectories named for the types of scripts to be
generated. These should include \fIdeploy\fR, \fIrevert\fR, and \fIverify\fR, but you
can create any number of other directories to create additional scripts that
will end up in a directory of the same name.
.PP
Each directory should include one or more files ending in \fI.tmpl\fR. 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 \f(CW\*(C`\-\-template\*(C'\fR option
to have Sqitch use a different file.
.PP
For example, say you have this directory structure:
.PP
.Vb 7
\& 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
.Ve
.PP
Assuming that you're using the PostgreSQL engine, the code for which is \f(CW\*(C`pg\*(C'\fR,
when you add a new change like so:
.PP
.Vb 1
\& sqitch add schema \-n \*(AqCreates schema\*(Aq
.Ve
.PP
Sqitch will use the \f(CW\*(C`pg.tmpl\*(C'\fR files to create the following files in the
top directory configured for the project (See sqitch-configuration for
details).
.PP
.Vb 4
\& deploy/schema.sql
\& revert/schema.sql
\& test/schema.sql
\& verify/schema.sql
.Ve
.PP
If you want to use the \f(CW\*(C`create_table\*(C'\fR templates, instead, use the
\&\f(CW\*(C`\-\-template\*(C'\fR option, like so:
.PP
.Vb 1
\& sqitch add user_table \-\-template create_table \-n \*(AqCreate user table\*(Aq
.Ve
.PP
Sqitch will use the \f(CW\*(C`create_table.tmpl\*(C'\fR files to create the following files
in the top directory configured for the project (See sqitch-configuration
for details).
.PP
.Vb 3
\& deploy/user_table.sql
\& revert/user_table.sql
\& verify/user_table.sql
.Ve
.PP
Note that the \f(CW\*(C`test\*(C'\fR file was not created, because no
\&\fItest/create_table.tmpl\fR template file exists.
.SS Syntax
.IX Subsection "Syntax"
The syntax of Sqitch templates is the very simple language provided by
Template::Tiny, which is limited to:
.ie n .IP """[% %]""" 4
.el .IP "\f(CW[% %]\fR" 4
.IX Item "[% %]"
This is the directive syntax. By default, the return value of the expression
is output:
.Sp
.Vb 1
\& \-\- Deploy [% project %]:[% change %] to [% engine %]
.Ve
.Sp
You can add \f(CW\*(C`\-\*(C'\fR to the immediate start or end of a directive tag to control
the whitespace chomping options:
.Sp
.Vb 3
\& [% IF foo \-%] # remove trailing newline
\& We have foo!
\& [%\- END %] # remove leading newline
.Ve
.ie n .IP """[% IF %]""" 4
.el .IP "\f(CW[% IF %]\fR" 4
.IX Item "[% IF %]"
.PD 0
.ie n .IP """[% IF %] / [% ELSE %]""" 4
.el .IP "\f(CW[% IF %] / [% ELSE %]\fR" 4
.IX Item "[% IF %] / [% ELSE %]"
.ie n .IP """[% UNLESS %]""" 4
.el .IP "\f(CW[% UNLESS %]\fR" 4
.IX Item "[% UNLESS %]"
.PD
Conditional blocks:
.Sp
.Vb 5
\& [% IF transactions %]
\& BEGIN;
\& [% ELSE %]
\& \-\- No transaction, beware!
\& [% END %]
.Ve
.ie n .IP """[% FOREACH item IN list %]""" 4
.el .IP "\f(CW[% FOREACH item IN list %]\fR" 4
.IX Item "[% FOREACH item IN list %]"
Loop over a list of values:
.Sp
.Vb 3
\& [% FOREACH item IN requires \-%]
\& \-\- requires: [% item %]
\& [% END \-%]
.Ve
.PP
If this is not sufficient for your needs, simply install Template::Toolkit
and all templates will be processed by its more comprehensive features. See
the complete Template Toolkit documentation for
details, especially the syntax docs
.SS Variables
.IX Subsection "Variables"
Sqitch defines five variables for all templates. Any number of additional
variables can be added via the \f(CW\*(C`\-\-set\*(C'\fR option, like so:
.PP
.Vb 1
\& sqitch add \-\-set transactions=1 \-\-set schema=foo
.Ve
.PP
Any number of variables may be specified in this manner. You may then use
those variables in custom templates. Variables that appear multiple times will
be passed to the templates as lists of values for which you will likely want
to use \f(CW\*(C`[% FOREACH %]\*(C'\fR. If the templates do not reference your variables,
they will be ignored. Variables may also be specified in a \f(CW\*(C`add.variables\*(C'\fR
config section (see "Configuration Variables"). Variables
specified via \f(CW\*(C`\-\-set\*(C'\fR will override configuration variables.
.PP
The five core variables are:
.ie n .IP """change""" 4
.el .IP \f(CWchange\fR 4
.IX Item "change"
The name of the change being added.
.ie n .IP """engine""" 4
.el .IP \f(CWengine\fR 4
.IX Item "engine"
The name of the engine for which the change was added. One of \f(CW\*(C`pg\*(C'\fR,
\&\f(CW\*(C`sqlite\*(C'\fR, \f(CW\*(C`mysql\*(C'\fR, \f(CW\*(C`oracle\*(C'\fR, \f(CW\*(C`firebird\*(C'\fR, \f(CW\*(C`vertica\*(C'\fR \f(CW\*(C`exasol\*(C'\fR, or
\&\f(CW\*(C`snowflake\*(C'\fR.
.ie n .IP """project""" 4
.el .IP \f(CWproject\fR 4
.IX Item "project"
The name of the Sqitch project to which the change was added. The project name
is set in the plan by the "\f(CW\*(C`init\*(C'\fR command"|sqitch\-init>.
.ie n .IP """requires""" 4
.el .IP \f(CWrequires\fR 4
.IX Item "requires"
A list of required changes as passed via one or more instances of the
\&\f(CW\*(C`\-\-requires\*(C'\fR option.
.ie n .IP """conflicts""" 4
.el .IP \f(CWconflicts\fR 4
.IX Item "conflicts"
A list of conflicting changes as passed via one or more instances of the
\&\f(CW\*(C`\-\-conflicts\*(C'\fR option.
.SH "Configuration Variables"
.IX Header "Configuration Variables"
.ie n .IP """add.all""" 4
.el .IP \f(CWadd.all\fR 4
.IX Item "add.all"
Add the change to all the plans in the project. Useful for multi-plan projects
in which changes should be kept in sync. May be overridden by \f(CW\*(C`\-\-all\*(C'\fR,
\&\f(CW\*(C`\-\-no\-all\*(C'\fR, or target, engine, and plan file name arguments.
.ie n .IP """add.template_directory""" 4
.el .IP \f(CWadd.template_directory\fR 4
.IX Item "add.template_directory"
Directory in which to find the templates. Any templates found in this
directory take precedence over user\- or system-specific templates, and may in
turn be overridden by the \f(CW\*(C`\-\-use\*(C'\fR option.
.ie n .IP """add.template_name""" 4
.el .IP \f(CWadd.template_name\fR 4
.IX Item "add.template_name"
Name used for template files. Should not include the \fI.tmpl\fR suffix.
Overrides the default, which is the name of the database engine, and may in
turn be overridden by the \f(CW\*(C`\-\-template\*(C'\fR option.
.ie n .IP """[add.templates]""" 4
.el .IP \f(CW[add.templates]\fR 4
.IX Item "[add.templates]"
Location of templates of different types. Core templates include:
.RS 4
.ie n .IP """add.templates.deploy""" 4
.el .IP \f(CWadd.templates.deploy\fR 4
.IX Item "add.templates.deploy"
.PD 0
.ie n .IP """add.templates.revert""" 4
.el .IP \f(CWadd.templates.revert\fR 4
.IX Item "add.templates.revert"
.ie n .IP """add.templates.verify""" 4
.el .IP \f(CWadd.templates.verify\fR 4
.IX Item "add.templates.verify"
.RE
.RS 4
.PD
.Sp
But a custom template type can have its location specified here, as well,
such as \f(CW\*(C`add.template.unit_test\*(C'\fR. May be overridden by \f(CW\*(C`\-\-use\*(C'\fR.
.RE
.ie n .IP """[add.variables]""" 4
.el .IP \f(CW[add.variables]\fR 4
.IX Item "[add.variables]"
A section defining template variables. Useful if you've customized templates
with your own variables and want project\-, user\-, or system-specific defaults
for them.
.ie n .IP """add.open_editor""" 4
.el .IP \f(CWadd.open_editor\fR 4
.IX Item "add.open_editor"
Boolean indicating if the add command should spawn an editor after generating
change scripts. When true, equivalent to passing \f(CW\*(C`\-\-edit\*(C'\fR. Defaults off.
.SH Sqitch
.IX Header "Sqitch"
Part of the sqitch suite.