sqitch-add(3pm)

💖 NAME 💖

hey bestie!! this is sqitch-add, and it lives in the User Contributed Perl Documentation (that's the (3pm) vibe, iykyk). ✨

• sqitch-add — add a database change to plans 🎀

---

✨ SYNOPSIS ✨

lowkey the whole flex in one block:

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

(and yes, that first line is exactly what it says, no cap 💅)

---

🦋 DESCRIPTION 🦋

okay so. this command adds a database change to one or more plans. and like, it's giving ✨project✨ because it also creates script files in the deploy, revert, and verify directories, and possibly others too 👀. the content of those files? determined by the evaluation of templates. by default, system templates in $(prefix)/etc/sqitch/templates are what get used. and a single user can override that by making their own templates in ~/.sqitch/templates/ — see "Templates" for the deets, bestie.

the paths and extensions of the generated scripts depend on the configuration of Sqitch targets, engines, and the core. see sqitch-configuration for all of that. 🌈

nota bene, bestie: the name of the new change must adhere to the rules as defined in sqitchchanges. no chaotic naming, we don't do that here 🙈

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 lowkey works so well for projects with a single plan but separate top directories for each engine, for example. so clean. 🌸

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. one command, every plan, main character energy fr fr 👑

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, we don't judge 💅). see "Examples" for examples.

---

💅 OPTIONS 💅

• -c, --change, --change-name — the name of the change to add. you can specify the name with or without this option, but the option is highkey 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, snowflake, cockroach, or clickhouse). 🎀

• --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. slay 💅
• -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 🎀

Okay so bestie, Sqitch ships with a super simple little set of templates for generating the deploy, revert, and verify scripts — and you can absolutely make your own. 💅

By default, Sqitch uses system-wide templates installed in $(prefix)/etc/sqitch/templates. Wanna know where that actually is? Run sqitch --etc-path (like, "$(sqitch --etc-path)/templates", iykyk). You can override individual templates on a user basis by copying them into ~/.sqitch/templates and editing them however you want. And you can also override them with the --template-directory or --template-name options, plus the template-specific options. So many layers, so much power. ✨

🌸 Directory Layout 🌸

Sqitch looks for templates in these directories, in this exact order:

• --template-directory or add.template_directory
• ~/.sqitch/templates/
• $(prefix)/etc/sqitch/templates

Each one should have subdirectories named after the types of scripts you're generating. Those should include deploy, revert, and verify, but honestly you can make as many other directories as you like, and each one creates additional scripts that land in a directory of the same name. Go off. 🦋

Each directory should have one or more files ending in .tmpl. The main part of the file name can be literally anything, but by default Sqitch looks for a file named after the database engine. Use the --template option to make Sqitch use a different file instead.

So like, say your directory structure looks like this:

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 you're on the PostgreSQL engine, whose code 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 these files in the top directory configured for the project (check out sqitch-configuration for the deets):

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

But say you wanna use the create_table templates instead — just hit it with the --template option, like:

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

Then Sqitch will use the create_table.tmpl files to create these files in the top directory configured for the project (again, see sqitch-configuration for details):

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

And notice — the test file did not get created, because there's no test/create_table.tmpl template file. No template, no file, that's the vibe check. 💀

⭐ 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 gets 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 -%]

And if all that is somehow not enough for your needs, just install Template::Toolkit and every template gets processed by its way more comprehensive feature set. Go read the complete Template Toolkit documentation at http://tt2.org/docs/manual/ for details — especially the syntax docs at http://tt2.org/docs/manual/Syntax.html. Obsessed. 🫶

💜 Variables 💜

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

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

You can specify as many variables this way as you want, and then use them in custom templates. If a variable shows up multiple times, it gets passed to the templates as a list of values — and for that you'll probably want [% FOREACH %]. If your templates never reference your variables, they just get ignored, no biggie. Variables can also be set in an add.variables config section (peep "Configuration Variables" below). And heads up: variables set via --set override configuration variables. Periodt.

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, snowflake, cockroach, or clickhouse).
• project — the name of the Sqitch project to which the change was added. The project name is set in the plan by the sqitch-init command.
• 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. So useful for multi-plan projects where changes should be kept in sync. Can be overridden by --all, --no-all, or target, engine, and plan file name arguments.
• add.template_directory — the directory in which to find the templates. Any templates in this directory take precedence over user- or system-specific templates, and can in turn be overridden by the --use option.
• add.template_name — the name used for template files. Should not include the .tmpl suffix. Overrides the default (which is the name of the database engine), and can in turn be overridden by the --template option.
• [add.templates] — where templates of different types live. Core templates include:
  • add.templates.deploy
  • add.templates.revert
  • add.templates.verify

But a custom template type can have its location specified here too, like add.template.unit_test. May be overridden by --use.

• [add.variables] — a section defining template variables. Chef's kiss if you've customized templates with your own variables and want project-, user-, or system-specific defaults for them. 🍓
• add.open_editor — a boolean saying whether the add command should spawn an editor after generating change scripts. When true, it's equivalent to passing --edit. Defaults off.

👑 Sqitch 👑

Part of the sqitch suite. Obviously. Main character behavior.

---

💖 And that's the whole page, bestie! This was sqitch-add(3pm) from perl v5.40.1, dated 2026-07-26 — go forth and add changes like the icon you are. ✨🎀🦋