Provided by: sqitch_1.4.1-1_all bug

Name

       sqitch-environment - Environment variables recognized by Sqitch

Description

       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 Environment
       "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_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.

       "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 <https://github.com/sqitchers/docker-
           sqitch/blob/main/docker-sqitch.sh>.

       "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 <https://github.com/sqitchers/docker-
           sqitch/blob/main/docker-sqitch.sh>.  This value will be used only when neither the
           $SQITCH_FULLNAME nor the "user.name" sqitch-config variable is set.

       "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 <https://github.com/sqitchers/docker-
           sqitch/blob/main/docker-sqitch.sh>.  This value will be used only when neither the
           $SQITCH_EMAIL nor the "user.email" sqitch-config variable is set.

       "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.

       "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".

   Engine Environments
       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.

       PostgreSQL, YugabyteDB, CockroachDB

       All the usual PostgreSQL environment variables
       <https://www.postgresql.org/docs/current/static/libpq-envars.html> 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.

       "PGPASSWORD"
           The password to use to connect to the server. Superseded by $SQITCH_PASSWORD and the
           target URI 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

       SQLite provides no environment variable support.

       MySQL

       Sqitch recognizes and takes advantage of the following MySQL environment variables
       <https://dev.mysql.com/doc/refman/5.7/en/environment-variables.html>:

       "MYSQL_PWD"
           The password to use to connect to the server. Superseded by $SQITCH_PASSWORD and the
           target URI password.

       "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.

       Oracle

       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.

       "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.

       Firebird

       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.

       Vertica

       Sqitch provides explicit support for the following Vertica environment variables
       <https://www.vertica.com/docs/8.1.x/HTML/index.htm#Authoring/ConnectingToVertica/vsql/vsqlEnvironmentVariables.htm>:

       "VSQL_USER"
           The username to use to connect to the server. Superseded by $SQITCH_USERNAME and the
           target URI username.

       "VSQL_PASSWORD"
           The password to use to connect to the server. Superseded by $SQITCH_PASSWORD and the
           target URI 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 name of the database to connect to. Superseded by the target URI database name.

       Exasol

       The Sqitch Exasol engine supports no special environment variables. It does, however,
       override THE "SQLPATH" environment variable, to prevent EXAplus executing SQL scripts
       unexpectedly.

       Snowflake

       Sqitch provides explicit support for the following Snowflake environment variables
       <https://docs.snowflake.com/en/user-guide/snowsql-start.html#connection-syntax>:

       "SNOWSQL_ACCOUNT"
           The name assigned to the snowflake account. Superseded by the target URI host name.

       "SNOWSQL_USER"
           The username to use to connect to the server. Superseded by $SQITCH_USERNAME and the
           target URI username.

       "SNOWSQL_PWD"
           The password to use to connect to the server. Superseded by $SQITCH_PASSWORD and the
           target URI password.

       "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.

       "SNOWSQL_DATABASE"
           The name of the database to connect to. Superseded by the target URI database name.

       "SNOWSQL_WAREHOUSE"
           The warehouse to use. Superseded by the target URI database "warehouse" query
           parameter.

       "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.

See Also

       •   sqitch-configuration

       •   sqitch-config

       •   sqitch-authentication

Sqitch

       Part of the sqitch suite.