Sqitch

sqitch-add

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

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:

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:

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

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:

Configuration Variables

Sqitch

Part of the sqitch suite.