sqitch-add - Add a database change to the plan
sqitch [options] add [<dependency-options>] [<template-options>] name
Add a database change to the plan. This will result in the creation of script files with the --extension extension in the --deploy-dir, --revert-dir, and --verify-dir directories, and possibly others. The content of these files is determined by the evaluation of templates. By default, system templates in $(etc_path)/templates are used. These can be overridden by a single user by creating templates in ~/.sqitch/templates/ See "Templates" for details.
--extension
--deploy-dir
--revert-dir
--verify-dir
Note that the name of the new change must adhere to the rules as defined in sqitchchanges.
-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.
-c
--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.
-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.
-m
-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.'.
name=value
--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 $($etc_prefix)/templates.
add
-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, or vertica.
pg
sqlite
mysql
oracle
firebird
vertica
--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.
add.open_editor
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 ($etc_path)/templates; call sqitch --etc-path to find out where, exactly. 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.
sqitch --etc-path
Sqitch looks for templates in the following directories, and in this order:
--template-directory or add.template_directory
add.template_directory
~/.sqitch/templates/
($etc_path)/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 --top-dir:
pg.tmpl
--top-dir
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:
create_table
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 --top-dir:
create_table.tmpl
deploy/user_table.sql revert/user_table.sql verify/user_table.sql
Note that the test file was not created, because no test/crate_table.tmpl file exists.
test
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 [% change %]
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 for details, especially the syntax docs
Sqitch defines three 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.
[% FOREACH %]
[add "variables]
The three core variables are:
change
The name of the change being added.
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.
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.
--use
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.template.unit_test
[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.
Boolean indicating if the add command should spawn an editor after generating change scripts. When true, equivalent to passing --edit. Defaults off.
Part of the sqitch suite.
To install App::Sqitch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Sqitch
CPAN shell
perl -MCPAN -e shell install App::Sqitch
For more information on module installation, please visit the detailed CPAN module installation guide.