sqitch-environment - Environment variables recognized by Sqitch
Sqitch supports a number of environment variables that affect its functionality. This document lists them all, along with brief descriptions of their purposes and pointers to relevant documentation.
SQITCH_CONFIG
Path to the project configuration file. Overrides the default, which is ./sqitch.conf. See sqitch-config for details.
SQITCH_USER_CONFIG
Path to the user's configuration file. Overrides the default, which is ./.sqitch/sqitch.conf. See sqitch-config for details.
SQITCH_SYSTEM_CONFIG
Path to the system's configuration file. Overrides the default, which is a file named sqitch.conf in the directory identified by sqitch --etc. See sqitch-config for details.
sqitch.conf
sqitch --etc
SQITCH_TARGET
The name or URI of the database target to connect to. Overrides values stored in the configuration, but not command-line options or arguments.
SQITCH_USERNAME
Username to use when connecting to a database, for those database engines that support authentication. Overrides values stored in a target URI or the configuration. See sqitch-authentication for details.
SQITCH_PASSWORD
Password to use when connecting to a database, for those database engines that support authentication. Overrides values stored in a target URI or the configuration. See sqitch-authentication for details.
SQITCH_FULLNAME
Full name of the current user. Used to identify the user adding a change to a plan file or deploying a change. Supersedes the <user.name> sqitch-config variable.
SQITCH_EMAIL
Email address of the current user. Used to identify the user adding a change to a plan file or deploying a change. Supersedes the user.email sqitch-config variable.
user.email
SQITCH_ORIG_SYSUSER
Username from the original system. Intended for use by scripts that run Sqitch from another host, where the originating host username should be passed to the execution host, such as this Docker script.
SQITCH_ORIG_FULLNAME
Full name of the original system user. Intended for use by scripts that run Sqitch from another host, where the originating host user's identity should be passed to the execution host, such as this Docker script. This value will be used only when neither the $SQITCH_FULLNAME nor the user.name sqitch-config variable is set.
$SQITCH_FULLNAME
user.name
SQITCH_ORIG_EMAIL
Email address of the original user. Intended for use by scripts that run Sqitch on a separate host, where the originating host user's identity should be passed to the execution host, such as this Docker script. This value will be used only when neither the $SQITCH_EMAIL nor the user.email sqitch-config variable is set.
$SQITCH_EMAIL
SQITCH_EDITOR
The editor that Sqitch will launch when the user needs to edit some text (a change note, for example). If unset, the core.editor configuration variable will be used. If it's not set, $VISUAL or $EDITOR will be consulted (in that order). Finally, if none of these are set, Sqitch will invoke notepad.exe on Windows and vi elsewhere.
core.editor
$VISUAL
$EDITOR
notepad.exe
vi
SQITCH_PAGER
The pager program that Sqitch will use when a command (like sqitch log) produces multi-page output. If unset, the core.pager configuration variable will be used. If this is also not set, the PAGER environment variable will be used. Finally, if none of these are set, Sqitch will attempt to find and use one of the commonly used pager programs like less and more.
sqitch log
core.pager
PAGER
less
more
In addition to Sqitch's environment variables, some of the database engines support environment variables of their own. These are not comprehensive for all variables supported by a database engine, but document those supported by Sqitch's implementation for each engine.
All the usual PostgreSQL environment variables should be implicitly used. However, the following variables are explicitly recognized by Sqitch:
PGUSER
The username to use to connect to the server. Superseded by $SQITCH_USERNAME and the target URI username.
$SQITCH_USERNAME
PGPASSWORD
The password to use to connect to the server. Superseded by $SQITCH_PASSWORD and the target URI password.
$SQITCH_PASSWORD
PGHOST
The PostgreSQL server host to connect to. Superseded by the target URI host name.
PGPORT
The PostgreSQL server port to connect to. Superseded by the target URI port.
PGDATABASE
The name of the database to connect to. Superseded by the target URI database name.
SQLite provides no environment variable support.
Sqitch recognizes and takes advantage of the following MySQL environment variables:
MYSQL_PWD
MYSQL_HOST
The MySQL server host to connect to. Superseded by the target URI host name.
MYSQL_TCP_PORT
The MySQL server port to connect to. Superseded by the target URI port.
Sqitch's Oracle engine supports a few environment variables:
ORACLE_HOME
Required to point to the Oracle home directory, and contain both the SQL*Plus client and the shared libraries with which the Perl Oracle driver was compiled.
TNS_ADMIN
The directory in which the Oracle networking interface will find its configuration files, notably tnsnames.ora. Defaults to $ORACLE HOME/network/admin if not set.
$ORACLE HOME/network/admin
TWO_TASK
The name of the Oracle database to connect to. Superseded by the target URI.
LOCAL
The name of the Oracle database to connect to. Windows only. Superseded by the target URI.
ORACLE_SID
The System Identifier (SID) representing the Oracle database to connect to. Superseded by the target URI, TWO_TASK and LOCAL on Windows.
In addition, the Oracle engine in Sqitch explicitly overrides the NLS_LANG and SQLPATH environment variables. The former is set to AMERICAN_AMERICA.AL32UTF8 to ensure that all database connections use the UTF-8 encoding. The latter is set to an empty string, to prevent SQL*Plus executing SQL scripts unexpectedly.
NLS_LANG
SQLPATH
AMERICAN_AMERICA.AL32UTF8
The Sqitch Firebird engine supports the following environment variables:
ISC_USER
The username to use to connect to Firebird. Superseded by $SQITCH_USERNAME and the target URI username.
ISC_PASSWORD
The password to use to connect to Firebird. Superseded by $SQITCH_PASSWORD and the target URI password.
Sqitch provides explicit support for the following Vertica environment variables:
VSQL_USER
VSQL_PASSWORD
VSQL_HOST
The Vertica server host to connect to. Superseded by the target URI host name.
VSQL_PORT
The Vertica server port to connect to. Superseded by the target URI port.
VSQL_DATABASE
The Sqitch Exasol engine supports no special environment variables. It does, however, override THE SQLPATH environment variable, to prevent EXAplus executing SQL scripts unexpectedly.
Sqitch provides explicit support for the following Snowflake environment variables:
SNOWSQL_ACCOUNT
The name assigned to the snowflake account. Superseded by the target URI host name.
SNOWSQL_USER
SNOWSQL_PWD
SNOWSQL_PRIVATE_KEY_PASSPHRASE
The passphrase for the private key file when using key pair authentication. See sqitch-authentication for details.
SNOWSQL_ROLE
The role to use when connecting to the server. Superseded by the target URI database role query parameter.
role
SNOWSQL_DATABASE
SNOWSQL_WAREHOUSE
The warehouse to use. Superseded by the target URI database warehouse query parameter.
warehouse
SNOWSQL_HOST
The Snowflake server host to connect to. Superseded by the target URI host name. Deprecated by Snowflake.
SNOWSQL_PORT
The Snowflake server port to connect to. Superseded by the target URI port. Deprecated by Snowflake.
SNOWSQL_REGION
The Snowflake region. Superseded by the target URI host name. Deprecated by Snowflake.
sqitch-configuration
sqitch-config
sqitch-authentication
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.