Syntax

The syntax is fairly flexible and permissive; white space is mostly ignored. The "#" and ";" characters begin comments to the end of line, blank lines are ignored.

The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next section begins. Section names are not case sensitive. Only alphanumeric characters, "-" and "." are allowed in section names. Each variable must belong to some section, which means that there must be a section header before the first setting of a variable.

Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name, in the section header, like in the example below:

     [section "subsection"]

Subsection names are case sensitive and can contain any characters except newline (double quote and backslash have to be escaped as "\"" and "\\", respectively). Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have "[section]" if you have "[section "subsection"]", but you don't need to.

All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form "name = value". If there is no equal sign on the line, the entire line is taken as name and the variable is recognized as boolean "true". The variable names are case-insensitive, allow only alphanumeric characters and "-", and must start with an alphabetic character. There can be more than one value for a given variable; we say then that the variable is multivalued.

Leading and trailing whitespace in a variable value is discarded. Internal whitespace within a variable value is retained verbatim.

The values following the equals sign in variable assignments are either strings, integers, numbers, or booleans. Boolean values may be given as yes/no, 1/0, true/false or on/off. Case is not significant in boolean values, when converting value to the canonical form using the "--bool" type specifier; "sqitch config" will ensure that the output is "true" or "false".

String values may be entirely or partially enclosed in double quotes. You need to enclose variable values in double quotes if you want to preserve leading or trailing whitespace, or if the variable value contains comment characters (i.e. it contains "#" or ";"). Double quote and backslash characters in variable values must be escaped: use "\"" for """ and "\\" for "\".

The following escape sequences (beside "\"" and "\\") are recognized: "\n" for newline character (NL), "\t" for horizontal tabulation (HT, TAB) and "\b" for backspace (BS). No other character escape sequence or octal character sequence is valid.

Variable values ending in a "\" are continued on the next line in the customary UNIX fashion.

Some variables may require a special value format.

Example

  # Core variables
  [core]
      engine    = pg
      top_dir   = migrations
      extension = ddl
  [engine "pg"]
      registry  = widgetopolis
  [revert]
      to        = gamma
  [bundle]
      from      = gamma
      tags_only = yes
      dest_dir  = _build/sql

Variables

Note that this list is not comprehensive and not necessarily complete. For command-specific variables, you will find a more detailed description in the appropriate manual page.

"core.plan_file"

The plan file to use. Defaults to $top_dir/sqitch.plan.

"core.engine"

The database engine to use. Supported engines include:

"core.top_dir"

Path to directory containing deploy, revert, and verify SQL scripts. It should contain subdirectories named "deploy", "revert", and (optionally) "verify". These may be overridden by "deploy_dir", "revert_dir", and "verify_dir". Defaults to ".".

"core.deploy_dir"

Path to a directory containing SQL deployment scripts. Overrides the value implied by "core.top_dir".

"core.revert_dir"

Path to a directory containing SQL reversion scripts. Overrides the value implied by "core.top_dir".

"core.verify_dir"

Path to a directory containing SQL verify scripts. Overrides the value implied by "core.top_dir".

"core.extension"

The file name extension on deploy, revert, and verify SQL scripts. Defaults to "sql".

"core.verbosity"

An integer determining how verbose Sqitch should be. Defaults to 1. Set to 0 to silence status messages and to 2 or three to increase verbosity. Error message output will not be affected by this property.

"core.pager"

The command to use as a pager program. This overrides the "PAGER" environment variable on UNIX like systems. Both can be overridden by setting the $SQITCH_PAGER environment variable. If none of these variables are set, Sqitch makes a best-effort search among the commonly installed pager programs like "less" and "more".

"core.editor"

The command to use as a editor program. This overrides the "EDITOR" environment variable on UNIX like systems. Both can be overridden by setting the $SQITCH_EDITOR environment variable. If none of these variables are set, Sqitch defaults to "notepad.exe" on Windows and "vi" elsewhere.

"user"

Configuration properties that identify the user.

"user.name"

Your full name, to be recorded in changes and tags added to the plan, and to commits to the database.

"user.email"

Your email address, to be recorded in changes and tags added to the plan, and to commits to the database.

"engine.$engine"

Each supported engine offers a set of configuration variables, falling under the key "engine.$engine" where $engine may be any value accepted for "core.engine".

"engine.$engine.target"

A database target, either the name of target managed by the "target" command, or a database connection URI. If it's a target name, then the associated "uri", "registry", and "client" values will override any values specified for the values below. Targets are the preferred way to configure engines on a per-database basis, and the one specified here should be considered the default.

"engine.$engine.uri"

A database connection URI.

"engine.$engine.registry"

The name of the Sqitch registry schema or database. Sqitch will store its own data in this schema.

"engine.$engine.client"

Path to the engine command-line client. Defaults to the first instance found in the path.

Notes on engine-specific configuration:

"engine.pg.registry"

For the PostgreSQL engine, the "registry" value identifies the schema for Sqitch to use for its own data. No other data should be stored there. Defaults to "sqitch".

"engine.sqlite.registry"

For the SQLite engine, if the "registry" value looks like an absolute path, then it will be the database file. Otherwise, it will be in the same directory as the database specified by the "uri". Defaults to "sqitch".

"engine.mysql.registry"

For the MySQL engine, the "registry" value identifies the database for Sqitch to use for its own data. If you need to manage multiple databases on a single server, and don't want them all to share the same registry, change this property to a value specific for your database. Defaults to "sqitch".

"engine.oracle.registry"

For Oracle, "registry" value identifies the schema for Sqitch to use for its own data. No other data should be stored there. Uses the current schema by default (usually the same name as the connection user).

"engine.firebird.registry"

For the Firebird engine, if the "registry" value looks like an absolute path, then it will be the database file. Otherwise, it will be in the same directory as the database specified by the "uri". Defaults to "sqitch.$extension", where $extension is the same as that in the "uri", if any.

"engine.vertica.registry"

For the Vertica engine, the "registry" value identifies the schema for Sqitch to use for its own data. No other data should be stored there. Defaults to "sqitch".

"engine.exasol.registry"

For the Exasol engine, the "registry" value identifies the schema for Sqitch to use for its own data. No other data should be stored there. Defaults to "sqitch".

"engine.snowflake.registry"

For the Snowflake engine, the "registry" value identifies the schema for Sqitch to use for its own data. No other data should be stored there. Defaults to "sqitch".

"core.vcs"

Configuration properties for the version control system. Currently, only Git is supported.

"core.vcs.client"

Path to the "VCS" command-line client. Defaults to the first instance of git found in the path.

"user"

"user.email"

Your email address to be recorded in any newly planned changes.

"user.name"

Your full name to be recorded in any newly planned changes.