Name
sqitch-config - Get and set local, user, or system Sqitch options
Synopsis
sqitch config [<file-option>] [type] name [value [value_regex]]
sqitch config [<file-option>] [type] --add name value
sqitch config [<file-option>] [type] --replace-all name value [value_regex]
sqitch config [<file-option>] [type] --get name [value_regex]
sqitch config [<file-option>] [type] --get-all name [value_regex]
sqitch config [<file-option>] [type] --get-regexp name_regex [value_regex]
sqitch config [<file-option>] --unset name [value_regex]
sqitch config [<file-option>] --unset-all name [value_regex]
sqitch config [<file-option>] --rename-section old_name new_name
sqitch config [<file-option>] --remove-section name
sqitch config [<file-option>] -l | --list
sqitch config [<file-option>] -e | --edit
Description
You can query/set/replace/unset Sqitch options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped.
Multiple lines can be added to an option by using the --add
option. If you
want to update or unset an option which can occur on multiple lines, a Perl
regular expression value_regex
needs to be given. Only the existing values
that match the regex will be updated or unset. If you want to handle lines
that do not match the regex, just prepend a single !
(exclamation point) in
front (see Examples).
The type
specifier can be --int
, --num
, or --bool
, to ensure that
the variable(s) are of the given type and convert the value to the canonical
form (simple integer for --int
, decimal number for --num
, a “true” or
“false” string for --bool
) If no type specifier is passed, no checks or
transformations are performed on the value.
The file-option
can be one of --local
, --user
, --system
, or
--file
, which specify where the values will be read from or written to. The
default is to assume the local config file in the current project directory,
for editing, and the all files merged for fetching (see “Files”).
On success, the command returns the exit code 0.
Options
-
--replace-all
The default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the
value_regex
). -
--add
Adds a new line to the option without altering any existing values. This is the same as providing
^$
as the value_regex in--replace-all
. -
--get
Get the value for a given key (optionally filtered by a regex matching the value). Returns error code 1 if the key was not found and error code 2 if multiple values were found.
-
--get-all
Like
--get
, but does not fail if the number of values for the key is not exactly one. -
--get-regexp
Like
--get-all
, but interprets the name as a regular expression and writes out the key names and value. -
--local
For writing options: write to the local
./sqitch.conf
file. This is the default if no file option is specified.For reading options: read only from the local
./sqitch.conf
file rather than from all available files.See also “Files”.
-
--user
For writing options: write to the user
~/.sqitch/sqitch.conf
file rather than the repository./sqitch.conf
.For reading options: read only from the user
~/.sqitch/sqitch.conf
file rather than from all available files.See also “Files”.
-
--global
An alias for
--user
for the benefit of the muscle memory of Git users. -
--system
For writing options: write to system-wide
$(prefix)/etc/sqitch/sqitch.conf
file rather than the repository./sqitch.conf
.For reading options: read only from system-wide
$(prefix)/etc/sqitch/sqitch.conf
file rather than from all available files.Call
sqitch --etc-path
to find out exactly where the system configuration file lives (e.g.,$(sqitch --etc-path)/sqitch.conf
).See also “Files”.
-
-f config-file, --file config-file
Use the given config file instead of the one specified by
$SQITCH_CONFIG
. -
--remove-section
Remove the given section from the configuration file.
-
--rename-section
Rename the given section to a new name.
-
--unset
Remove the line matching the key from config file.
-
--unset-all
Remove all lines matching the key from config file.
-
-l, --list
List all variables set in config file.
-
--bool
sqitch config
will ensure that the output is “true” or “false”. -
--int
sqitch config
will ensure that the output is a simple integer. -
--num
sqitch config
will ensure that the output is a simple decimal number. -
--bool-or-int
sqitch config
will ensure that the output matches the format of either--bool
or--int
, as described above. -
-e, --edit
Opens an editor to modify the specified config file; either
--local
,--user
,--system
, or--file
. If none of those options is specified, the local file will be opened.
Files
If not set explicitly with --file
, there are three files in which
sqitch config
will search for configuration options:
-
./sqitch.conf
Local, project-specific configuration file.
-
~/.sqitch/sqitch.conf
User-specific configuration file.
-
$(prefix)/etc/sqitch/sqitch.conf
System-wide configuration file.
Environment
-
SQITCH_CONFIG
Take the local configuration from the given file instead of
./sqitch.conf
. -
SQITCH_USER_CONFIG
Take the user configuration from the given file instead of
~/.sqitch/sqitch.conf
. -
SQITCH_SYSTEM_CONFIG
Take the system configuration from the given file instead of
$($etc_prefix)/sqitch.conf
.
Examples
Given a ./sqitch.conf
like this:
#
# This is the config file, and
# a '#' or ';' character indicates
# a comment
#
; core variables
[core]
; Use PostgreSQL
engine = pg
; Bundle command settings.
[bundle]
from = gamma
tags_only = false
dest_dir = _build/sql
; Fuzzle command settings
[core "fuzzle"]
clack = foo
clack = bar
clack = barzlewidth
You can set the tags_only
setting to true with
% sqitch config bundle.tags_only true
The hypothetical clack
key in the core.fuzzle
section might need to set
foo
to “hi” instead of “foo”. You can make the replacement by passing an
additional argument to match the old value, which will be evaluated as a
regular expression. Here’s one way to make that change:
% sqitch config core.fuzzle.clack hi '^foo$'
To delete the entry for bundle.from
, do
% sqitch config --unset bundle.from
If you want to delete an entry for a multivalue setting (like
core.fuzzle.clack
), provide a regex matching the value of exactly one line.
This example deletes the “bar” value:
% sqitch config --unset core.fuzzle.clack '^bar$'
To query the value for a given key, do:
% sqitch config --get core.engine
Or:
% sqitch config core.engine
Or, to query a multivalue setting for only those values that match /ba/
:
% sqitch config --get core.fuzzle.clack ba
If you want to know all the values for a multivalue setting, do:
% sqitch config --get-all core.fuzzle.clack
If you like to live dangerously, you can replace all core.fuzzle.clack
with a
new one with
% sqitch config --replace-all core.fuzzle.clack funk
However, if you only want to replace lines that don’t match bar
, prepend
the matching regular expression with an exclamation point (!
), like so:
% sqitch config --replace-all core.fuzzle.clack yow '!bar'
To match only values with an exclamation mark, you have to escape it:
% sqitch config section.key '[!]'
To add a new setting without altering any of the existing ones, use:
% sqitch config --add core.fuzzle.set widget=fred
Configuration File
The sqitch configuration file contains a number of variables that affect the
sqitch command’s behavior. The ./sqitch.conf
file local to each project is
used to store the configuration for that project, and
$HOME/.sqitch/sqitch.conf
is used to store a per-user configuration as
fallback values for the ./sqitch.conf
file. The file
$($etc_prefix)/sqitch.conf
can be used to store a system-wide default
configuration.
The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive, allow only alphanumeric characters and -, and must start with an alphabetic character. Some variables may appear multiple times.
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:
pg
- PostgreSQL, Postgres-XC, and YugabyteDBsqlite
- SQLiteoracle
- Oraclemysql
- MySQL and MariaDBfirebird
- Firebirdvertica
- Verticaexasol
- Exasolsnowflake
- Snowflakecockroach
- CockroachDB
-
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 bydeploy_dir
,revert_dir
, andverify_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 likeless
andmore
. -
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 tonotepad.exe
on Windows andvi
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 associateduri
,registry
, andclient
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 tosqitch
. -
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 theuri
. Defaults tosqitch
. -
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 tosqitch
. -
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 theuri
. Defaults tosqitch.$extension
, where$extension
is the same as that in theuri
, 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 tosqitch
. -
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 tosqitch
. -
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 tosqitch
.
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 ofgit
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.
Sqitch
Part of the sqitch suite.