sqitch-config - Get and set local, user, or system Sqitch options
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
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).
--add
value_regex
!
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.
type
--int
--num
--bool
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).
file-option
--local
--user
--system
--file
On success, the command returns the exit code 0.
--replace-all
The default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the value_regex).
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.
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.
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.
For writing options: write to system-wide $(etc_path)/sqitch.conf file rather than the repository ./sqitch.conf.
For reading options: read only from system-wide $($etc_prefix)/sqitch.conf file rather than from all available files.
-f config-file, --file config-file
Use the given config file instead of the one specified by $SQITCH_CONFIG.
$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.
sqitch config will ensure that the output is "true" or "false".
sqitch config
sqitch config will ensure that the output is a simple integer.
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.
If not set explicitly with --file, there are three files in which sqitch config will search for configuration options:
Local, project-specific configuration file.
User-specific configuration file.
System-wide configuration file.
SQITCH_CONFIG
Take the local configuration from the given file instead of ./sqitch.conf.
./sqitch.conf
SQITCH_USER_CONFIG
Take the user configuration from the given file instead of ~/.sqitch/sqitch.conf.
~/.sqitch/sqitch.conf
SQITCH_SYSTEM_CONFIG
Take the system configuration from the given file instead of $($etc_prefix)/sqitch.conf.
$($etc_prefix)/sqitch.conf
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 ; Revert command settings [core "pg"] set = foo=bar set = baz=yo
You can set the the tags_only setting to true with
tags_only
% sqitch config bundle.tags_only true
The hypothetical set key in the core.pg section might need to set foo to "hi" instead of "bar". Here's how to make that change:
set
core.pg
foo
% sqitch config core.pg.set foo=bar foo=hi
To delete the entry for bundle.from, do
bundle.from
% sqitch config --unset bundle.from
If you want to delete an entry for a multivalue setting (like core.pg.set), provide a regex matching the value of exactly one line.
core.pg.set
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/:
/ba/
% sqitch config --get core.pg.set ba
If you want to know all the values for a multivalue setting, do:
% sqitch config --get-all core.pg.set
If you like to live dangerously, you can replace all core.pg.set with a new one with
% sqitch config --replace-all core.pg.set bring=funk
However, if you only want to replace the line without baz, do something like this:
baz
% sqitch config core.pg.set = '!baz'
To match only values with an exclamation mark, you have to escape them:
% sqitch config section.key value '[!]'
To add a new setting without altering any of the existing ones, use:
% sqitch config core.pg.set widget=fred
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.
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.
\"
\\
[section]
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.
name = value
true
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.
\n
\t
\b
Variable values ending in a \ are continued on the next line in the customary UNIX fashion.
Some variables may require a special value format.
# Core variables [core] engine = pg top_dir = migrations extension = ddl [core "pg"] db_name = widgetopolis [revert] to = gamma [bundle] from = gamma tags_only = yes dest_dir = _build/sql
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
pg
mysql - MySQL
mysql
sqlite - SQLite
sqlite
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 ./sql.
deploy
revert
verify
deploy_dir
revert_dir
verify_dir
./sql
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.
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.
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 to commits to the database.
user.email
Your email address, to be recorded in changes and tags added to the plan, and to to commits to the database.
Configuration properties for the PostgreSQL engine.
core.pg.client
Path to the psql command-line client. Defaults to the first instance found in the path.
psql
core.pg.username
User name to use when connecting to the PostgreSQL database. Defaults to the contents of the $PGUSER environment variable or to the current system user name.
$PGUSER
core.pg.password
Password to use when connecting to the PostgreSQL database. Defaults to the contents of the $PGPASSWORD environment variable or to the relevant line in ~/.pgpass, if available.
$PGPASSWORD
core.pg.db_name
Name of the PostgreSQL database. Defaults to the same as --db-user or to the contents of the PGDATABASE environment variable.
--db-user
PGDATABASE
core.pg.host
Host name to use when connecting to the database. Defaults to the contents of the $PGHOST environment variable.
$PGHOST
core.pg.port
Port number to connect to. Does not apply to all engines. Defaults to the contents of the $PGPORT environment variable.
$PGPORT
core.pg.sqitch_schema
The name of the schema in which Sqitch metadata will be stored. No other data should be stored in this schema. Defaults to sqitch.
sqitch
core.mysql
Configuration properties for the MySQL engine. All except client can also be set via the MySQL options file
client
core.mysql.client
Path to the mysql command-line client. Defaults to the first instance found in the path.
core.mysql.username
User name to use when connecting to the MySQL database.
core.mysql.password
Password to use when connecting to the MySQL database.
core.mysql.db_name
Name of the MySQL database.
core.mysql.host
Host name to use when connecting to the database.
core.mysql.port
Port number to connect to. Does not apply to all engines.
core.mysql.sqitch_prefix
Prefix to use for Sqitch metadata tables. Defaults to sqitch.
core.sqlite
Configuration properties for the SQLite engine.
core.sqlite.client
Path to the sqlite3 command-line client. Defaults to the first instance found in the path.
sqlite3
core.sqlite.db_name
Path to the SQLite database file.
core.sqlite.sqitch_db
Path to the file to use for the Sqitch database. This is where Sqitch will store all of its metadata. If you manage multiple databases with Sqitch, each should have its own corresponding Sqitch database. If you want the Sqitch metadata to be stored in the same file as the database it builds, make this value the same as core.sqlite.db_name. Defaults to sqitch.db in the same directory as db_name.
db_name
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.
VCS
Your email address to be recorded in any newly planned changes.
Your full name to be recorded in any newly planned changes.
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.