/ 
App-Sqitch-0.980
River stage one • 3 direct dependents • 3 total dependents
/ sqitch-add

Name

sqitch-add - Add a database change to the plan

Synopsis

sqitch [options] add [<dependency-options>] [<template-options>] name

Description

Add a database change to the plan. This will result in the creation of a new script files with the --extension extension in the --deploy-dir, --revert-dir, and --verify-dir directories. 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.

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

Options

-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 change targets 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 change targets 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.

-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 $($etc_prefix)/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 as follows:

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

This 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, or oracle.

--deploy-template
--revert-template
--verify-template

Path to the template for the given change script. Defaults to the individual templates found in --template-directory and using --template-name

--no-deploy
--no-revert
--no-verify

Do not generate the named script.

--deploy
--revert
--verify

Generate the named script. These are not mutually exclusive.

Templates

Sqitch contains a very simple set of templates for generating the deploy, revert, and verify scripts. By default, it 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 bases by copying templates to ~/.sqitch/tempates and making modifications. They may also be overridden by using the --template-directory or --template-name options, as well as the template-specific options.

Syntax

The syntax of the templates is the very simple but limited 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

Variables

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

sqitch add --set transations=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 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 --requiers option.

conflicts

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

Configuration Variables

add.template_directory

Directory in which to find the templates which should be named deploy.tmpl, revert.tmpl, and verify.tmpl. This will override looking for user- or system-specific templates, and may in turn be overridden by the --template-directory, --deploy-template, --revert-template, and --verify-template options.

add.with_deploy
add.with_revert
add.with_verify

Boolean variable indicating whether or not to generate the specified script when adding a change. They are all enabled by default. If you've disabled them but wish to create them for a given call to add, use the appropriate option: --deploy, --revert, or --verify.

add.deploy_template
add.revert_template
add.verify_template

Location of individual templates. My be overridden by the appropriate option: --deploy-template, --revert-template, or --verify-template.

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

Files

Unless explicitly told where to find templates via --template-directory or --template-name, or, as appropriate, --deploy-template, --user-template or --verify-template, Sqitch looks for templates named for the current engine in two locations for templates: A system-wide location and a user-specific location:

$(etc_path)/templates/deploy/$(engine).tmpl
$(etc_path)/templates/revert/$(engine).tmpl
$(etc_path)/templates/verify/$(engine).tmpl

The system-wide templates for creating deploy, revert, and verify scripts.

~/.sqitch/templates/deploy/$(engine).tmpl
~/.sqitch/templates/revert/$(engine).tmpl
~/.sqitch/templates/verify/$(engine).tmpl

User-specific templates to override the system-wide templates.

Sqitch

Part of the sqitch suite. x