Liquibase Environment Variables

The environment variable is a value that you can set once to pass configuration information to your application. It affects the behavior of running processes on a computer.

Liquibase Pro 4.4 and later versions can process configuration values from multiple sources, such as the liquibase.properties file, environment variables, Java system properties, and Liquibase Hub properties. This capability means the following:

  • You can use environment variables rather than storing hard-coded and plain-text values, such as usernames and passwords in documents and source control.
  • You can maintain better security and control specific configuration values more dynamically, especially when using build environments like Docker, AWS, Kubernetes, and others.
  • You can set both Liquibase global and command parameters as environment variables instead of passing them at runtime in the CLI or via the defaults file.
  • You can easily run Liquibase in partial or full automation with various build servers.

The use of LIQUIBASE_* environment variables requires a Liquibase Pro License key:

  • The Liquibase Pro License key is available for a free trial.
  • A lack of Liquibase Pro License key will not affect current wrapper scripts and homegrown tools which use environment variables to setup commands.
  • Without a Liquibase Pro key, Liquibase will continue to ignore existing LIQUIBASE_* environment variables when you run commands.

Using Liquibase Environment Variables

Tip: To see the list of all environment variables, check Liquibase Configuration Reference for Parameters and Environment Variables.

You can configure Liquibase environment variables by following these syntax rules:

  • Use underscores (_) for naming. If you use dots (.), convert them to underscores. Also, split the camel case values with an underscore.

Example: liquibase.logLevel is LIQUIBASE_LOG_LEVEL.

  • Do not use spaces within values.
  • Use uppercase letters.
  • Use the prefix of LIQUIBASE_ namespace.

Note: For default files, use the prefix of liquibase.. However, when running arguments in the CLI, you can drop the --liquibase- prefix.

Scoping Environment Variable for Global and Command Options

In Liquibase, there are two types of configuration options: global and command options.

  • Global options affect the overall usage of Liquibase, such as logLevel and classpath.
  • Command options are specific to the command, such as url or hubProjectID.

Use global options to the left of the command and command options to the right of the command.

As environment variables, there are three measures of scope:

  • LIQUIBASE_CLASSPATH configures a global option.
  • LIQUIBASE_COMMAND_USERNAME sets the username to use across all commands.
  • LIQUIBASE_COMMAND_UPDATE_USERNAME sets the username just for the update command.

Setting Environment Variables

To set the Liquibase environment variables, choose your operating system:

For Windows

  1. In your Windows search box, type env and select the Edit the System Environment option in the Control Panel.
  2. In the Advanced tab, select Environment Variables.
  3. In the Edit environment variable window, select New, and then add the variable name and value you need.

Example: LIQUIBASE_PRO_LICENSE_KEY
yj4v59bfdgj389btc4wg

  1. Select OK on all windows to close them.

For macOS/Linux/Unix

To set the Liquibase environment variable, in your terminal, use the export variable_name="value" command, which sets the variable and exports it to the global environment.

Example: export LIQUIBASE_PRO_LICENSE_KEY=yj4v59bfdgj389btc4wg

The export variable_name=value command will not permanently update your value after the termination of the session. To permanently update the value, edit your ~/.profile, ~/.bash_profile, or ~/.bashrc file to export the variable, and then source the file.

Configuration Hierarchy

Liquibase supports setting properties in multiple locations, with the final value determined in the chart in which the top locations take precedence over lower locations:

Command line arguments Override ServletConfig and ServletContext init parameters, Java system properties, OS environment variables, and configuration data
ServletConfig init parameters Override ServletContext init parameters, Java system properties, OS environment variables, and configuration data
ServletContext init parameters Override Java system properties, OS environment variables, and configuration data
Java system properties Override OS environment variables and configuration data
OS environment variables Override configuration data
Configuration data, such as liquibase.properties file, piped standard input, or defaults files Does not override any values

For example, if you want the logLevel=INFO property set for the DEV environment and logLevel=SEVERE set for the PROD environment, you should not specify these properties in the command line, but use environment variables instead.

Example: export LIQUIBASE_LOG_LEVEL="INFO" #what I set in my dev env

export LIQUIBASE_LOG_LEVEL="SEVERE" #what I set in my prod env

Note: Environment variables do not override the CLI usage. In automation driven by crafting dynamic CLI strings to execute, you need to reconcile commands and their arguments with specific settings in your environment variables that are overridden by the CLI usage.

Liquibase Naming Conventions for Environment Variables

Liquibase environment variables include:

  • All the GlobalConfiguration settings: LIQUIBASE_DATABASE_CHANGELOG_TABLE_NAME, LIQUIBASE_SCHEMA_NAME, and others.
  • All the HubConfiguration properties: LIQUIBASE_HUB_API_KEY, LIQUIBASE_HUB_URL, LIQUIBASE_HUB_MODE.
  • All the LiquibaseProConfiguration properties: LIQUIBASE_PRO_LICENSE_KEY, LIQUIBASE_PRO_MARK_UNUSED_NOT_DROPPED, LIQUIBASE_PRO_SYNONYMS_DROP_PUBLIC, LIQUIBASE_PRO_SQL_INLINE.

Security

If you use Liquibase environment variables, Liquibase only reads values from environment variables without writing any of them.

Related Links