sqitch-config(3pm)

📦
version 1.6.1 · 6 versions
, in ubuntu stonking

sqitch-config(3pm) — User Contributed Perl Documentation 💅

✨ NAME ✨

sqitch-config — get and set local, user, or system Sqitch options. It's giving config queen. 👑

📜 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 💁

Okay bestie, so sqitch config is your one-stop shop to query, set, replace, or unset Sqitch options. The <name> you pass is actually the section and the key separated by a dot, and the value gets escaped. Periodt.

You can add multiple lines to an option by using the --add option. If you wanna update or unset an option that can appear on multiple lines, you gotta give a Perl regular expression <value_regex>. Only the existing values that match that regex get updated or unset. And if you wanna handle lines that don't match the regex, just prepend a single ! (exclamation point) in front of it (see Examples). No cap.

The <type> specifier can be --int, --num, or --bool, to make sure the variable(s) are of that given type and convert the value to the canonical form: simple integer for --int, decimal number for --num, and a true or false string for --bool. If you don't pass a type specifier, no checks or transformations happen on the value. It's giving raw.

The <file-option> can be one of --local, --user, --system, or --file. Those tell it 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 all files merged for fetching (see "Files"). Slay.

On success, the command returns the exit code 0. 💅

✨ OPTIONS ✨

  • --replace-all — The default behavior is to replace at most one line. This one replaces all lines matching the key (and optionally the <value_regex>). Go off.
  • --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. Chill.
  • --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. We see you, Git girlies.
  • --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. Iykyk.

🔤 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. So lax, we love.

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. No skipping, bestie.

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. It's giving flexible.

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. Facts only. 💯

Okay so boom 💥 — the values that come after the equals sign in a variable assignment are one of: strings, integers, numbers, or booleans. Booleans can be written as yes/no, 1/0, true/false or on/off. Case does not matter for boolean values when you're converting the value to the canonical form using the --bool type specifier, and sqitch config will make absolutely sure the output is true or false. Periodt. 👑

String values may be entirely or partially wrapped in double quotes. And bestie you need those double quotes if you wanna preserve leading or trailing whitespace, or if your variable value contains comment characters (i.e. it contains # or ;). Double quote and backslash characters inside variable values must be escaped: use \" for " and \\ for \. No cap.

The following escape sequences (besides \" and \\) are recognized: \n for the 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. That's the whole list, that's the vibe check, that's it. 🚫

Variable values ending in a \ get continued on the next line, in the customary UNIX fashion. Iconic behavior honestly.

Some variables may require a special value format. (iykyk ✨)

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

Ok so real talk: this list is not comprehensive and not necessarily complete. For command-specific variables, you'll find a way more detailed description in the appropriate manual page. This is the highlight reel, not the director's cut. 💅

  • 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 the directory containing the 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 it 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 a 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, because every engine has its own little personality 🦋:

  • 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, the 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.
  • engine.clickhouse.registry — for the ClickHouse 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.
  • 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.

Sqitch

Part of the sqitch suite. 🫶

And that's a wrap bestie!! This whole thing came from perl v5.40.1, dated 2026-07-26, and it's known to the girlies as sqitch-config(3pm). Go configure something gorgeous. 💖✨🎀🦋🌸

📦 where this page comes from