Name

       sqitch-add - Add a database change to plans

Synopsis

         sqitch add widgets [options
         sqitch add blankets --all
         sqitch add --change sprockets pg sql
         sqitch add slinkies --require sprockets --set schema=industry

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 $(prefix)/etc/sqitch/templates are used. These can be overridden by a single
       user by creating templates in ~/.sqitch/templates/ See "Templates" for details.

       The paths and extensions of the generated scripts depend on the configuration of Sqitch
       targets, engines, and the core. See sqitch-configuration for details.

       Note that the name of the new change must adhere to the rules as defined in sqitchchanges.

       By default, the "add" 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 "--all" 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.

       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 "--change" to
       disambiguate the tag and change names from the other parameters if necessary (or
       preferable). See "Examples" for examples.

Options

       "-c"
       "--change"
       "--change-name"
           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.

       "-r"
       "--requires"
           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.

       "-x"
       "--conflicts"
           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.

       "-a"
       "--all"
           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 "add.all"
           configuration; use "--no-all" to override a true "add.all" configuration.

       "-n"
       "--note"
           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.

           For you Git folks out there, "-m" also works.

       "-s"
       "--set"
           Set a variable name and value for use in the templates. The format must be
           "name=value", e.g., "--set comment='This one is for you, babe.'".

       "--template-directory"
           Location to look for the templates. If none is specified, "add" will first look in
           ~/.sqitch/templates/ for each template, and fall back on
           $(prefix)/etc/sqitch/templates.

       "-t"
       "--template"
       "--template-name"
           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:

           "deploy/$name.tmpl"
           "revert/$name.tmpl"
           "verify/$name.tmpl"

           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 ("pg", "sqlite", "mysql", "oracle", "firebird", "vertica",
           "exasol", or "snowflake").

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

       "--with"
       "--without"
           Specify a type of template to generate or not generate.

       "-e"
       "--edit"
       "--open-editor"
           Open the generated change scripts in an editor.

       "--no-edit"
       "--no-open-editor"
           Do not open the change scripts in an editor. Useful when "add.open_editor" is true.

       "--plan-file"
       "-f"
           Path to the deployment plan file. Overrides target, engine, and core configuration
           values. Defaults to $top_dir/sqitch.plan.

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 "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 "extract" from a
       completely different Sqitch project named "utilities":

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

       Add a change that uses the "createtable" templates to generate the scripts, as well as
       variables to be used in that template (See
       <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 "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.'

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 $(prefix)/etc/sqitch/templates; call "sqitch --etc-path" to find
       out where, exactly (e.g., "$(sqitch --etc-path)/templates"). Individual templates may be
       overridden on a user basis by copying templates to ~/.sqitch/templates and making
       modifications. They may also be overridden by using the "--template-directory" or
       "--template-name" options, as well as the template-specific options.

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

       •   "--template-directory" or "add.template_directory"

       •   ~/.sqitch/templates/

       •   $(prefix)/etc/sqitch/templates

       Each should consist of subdirectories named for the types of scripts to be generated.
       These should include deploy, revert, and 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 .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 "--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 "pg", when you add
       a new change like so:

         sqitch add schema -n 'Creates schema'

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

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

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

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

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

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

       Note that the "test" file was not created, because no test/create_table.tmpl template file
       exists.

   Syntax
       The syntax of Sqitch templates is the very simple language provided by Template::Tiny,
       which is limited to:

       "[% %]"
           This is the directive syntax. By default, the return value of the expression is
           output:

             -- Deploy [% project %]:[% change %] to [% engine %]

           You can add "-" to the immediate start or end of a directive tag to control the
           whitespace chomping options:

             [% IF foo -%]    # remove trailing newline
             We have foo!
             [%- END %]       # remove leading newline

       "[% IF %]"
       "[% IF %] / [% ELSE %]"
       "[% UNLESS %]"
           Conditional blocks:

             [% IF transactions  %]
             BEGIN;
             [% ELSE %]
             -- No transaction, beware!
             [% END %]

       "[% FOREACH item IN list %]"
           Loop over a list of values:

             [% FOREACH item IN requires -%]
             -- requires: [% item %]
             [% END -%]

       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 <http://tt2.org/docs/manual/> for details, especially the syntax
       docs <http://tt2.org/docs/manual/Syntax.html>

   Variables
       Sqitch defines five variables for all templates. Any number of additional variables can be
       added via the "--set" option, like so:

         sqitch add --set transactions=1 --set schema=foo

       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 "[% FOREACH %]". If the templates
       do not reference your variables, they will be ignored. Variables may also be specified in
       a "add.variables" config section (see "Configuration Variables"). Variables specified via
       "--set" will override configuration variables.

       The five core variables are:

       "change"
           The name of the change being added.

       "engine"
           The name of the engine for which the change was added. One of "pg", "sqlite", "mysql",
           "oracle", "firebird", "vertica" "exasol", or "snowflake".

       "project"
           The name of the Sqitch project to which the change was added. The project name is set
           in the plan by the ""init" command"|sqitch-init>.

       "requires"
           A list of required changes as passed via one or more instances of the "--requires"
           option.

       "conflicts"
           A list of conflicting changes as passed via one or more instances of the "--conflicts"
           option.

Configuration Variables

       "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 "--all", "--no-all", or
           target, engine, and plan file name arguments.

       "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 "--use" option.

       "add.template_name"
           Name used for template files. Should not include the .tmpl suffix.  Overrides the
           default, which is the name of the database engine, and may in turn be overridden by
           the "--template" option.

       "[add.templates]"
           Location of templates of different types. Core templates include:

           "add.templates.deploy"
           "add.templates.revert"
           "add.templates.verify"

           But a custom template type can have its location specified here, as well, such as
           "add.template.unit_test". May be overridden by "--use".

       "[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.

       "add.open_editor"
           Boolean indicating if the add command should spawn an editor after generating change
           scripts.  When true, equivalent to passing "--edit".  Defaults off.

Sqitch

       Part of the sqitch suite.