Liquibase Environment Variables

Liquibase 4.4.0 and later adds environment variable support as an additional way to specify configuration information for Liquibase commands. You can use environment variables instead of using properties files, command line options, Maven parameters, and Java system properties. Between Liquibase 4.4.0 and 4.17.1, environment variables are only included in Liquibase Pro. In 4.18.0, environment variables are included in Liquibase Open Source.

An environment variable is a value that you can set to pass configuration information to your application. It affects the behavior of running processes on a computer and is associated with a process execution environment – either in a script or on the command line.

By using environment variables to specify Liquibase configuration, you can:

  • Improve security by not exposing sensitive configuration information like usernames, passwords, and command parameters on the command line or in liquibase.properties files stored in source control.
  • More easily share configuration information with Liquibase from DevOps platforms and tools (like Cloudbees, Docker, AWS, and Kubernetes).

What Liquibase environment variables are available?

For a list of available Liquibase environment variables, see the Liquibase Parameters page that documents all of the available Liquibase configuration options and the different ways options can be specified.

Liquibase Environment Variable Scopes

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

  • Global options affect the overall usage of Liquibase.
  • Command options are specific to a Liquibase command.

Different types of Liquibase environment variables have different scopes.

  • Global options
    • LIQUIBASE_<option-name> configures a global option available to all commands.
  • Command options
    • LIQUIBASE_COMMAND_<option-name> sets the username to use across all relevant commands.
    • LIQUIBASE_COMMAND_<command-name>_<option-name> sets the option for a specific command.

Environment variable format

Environment variables have the format <key>=<value>.

The key (by convention) is a descriptive string in upper-case letters with words separated by underscores.

Example key: LIQUIBASE_LOG_LEVEL

The value is a string of characters with no specific rules or conventions (other than what is expected by the related script or command).

Example value: WARNING

Note: Do not use spaces within values and use uppercase letters.

How to use environment variables with Liquibase

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

You can set a shell variable in your command line using the format <VARIABLE_NAME>=<VALUE>. However, this does not persist after you close your shell window. To turn a shell variable into an environment variable, use the export variable_name="value" command, which sets the variable and exports it to the global environment.

Example: export LIQUIBASE_LICENSE_KEY=yj4v59bfdgj389btc4wg

Format:

<VARIABLE_NAME>=<VALUE> liquibase <command>

Example:

> LIQUIBASE_LOG_LEVEL=INFO liquibase update

The export variable_name=value command does not permanently update your value after the termination of the session. To permanently update the value, edit your ~/.profile, ~/.bash_profile, or ~/.bashrc file and write a line using the export command to define each variable, and then use the source command on the file you stored your environment variable(s) in.

To set permanent environment variables for all users, create a file my_file.sh in the directory /etc/profile.d and use the export command to define each variable.

To unset an environment variable, use the syntax unset <VARIABLE_NAME>.

Windows

To set an environment variable in the Windows GUI:

  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.

    4. Example: LIQUIBASE_LICENSE_KEY

    yj4v59bfdgj389btc4wg

  4. Select OK on all windows to close them.

Alternatively, you can use the set command to set a temporary environment variable or the setx command to set a permanent environment variable from your command line:

Format:

set <VARIABLE_NAME>=<VALUE>
liquibase <command>

Example:

> set LIQUIBASE_LOG_LEVEL=INFO
>> liquibase update

Example: Use environment variables to control the amount of log information

For example, it’s typical to want more detailed logging information in development and test environments. In production, the focus is on responding to error situations, so additional details might obscure error messages and increase the time it takes to troubleshoot a problem.

To address this, you can configure Liquibase to vary the amount of logging information based on the target environment.

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.

In this example,

  • Non-production environments will have LIQUIBASE_LOG_LEVEL=”INFO”
  • Poduction environments will have LIQUIBASE_LOG_LEVEL=”SEVERE”
if ($EnvType = "Prod") then
 export LIQUIBASE_LOG_LEVEL="SEVERE"
else
 export LIQUIBASE_LOG_LEVEL="INFO"

<call Liquibase update command here>

Example: Use environment variables in Docker

For example, while building a demo in AWS CodeCommit, CodeBuild, & CodePipeline, imagine that your workflow requires you to pass in custom log data to build a friendlier dashboard in Grafana. Using the LIQUIBASE_CUSTOM_LOG_DATA_FILE environment variable will result in custom log data being omitted from the log, but passing the file in using the --custom-log-data-file argument, the custom log data is present as expected.

To pass environment variables to the Docker image, you must either use the Docker argument -e var=value or --env var=value. For example:

-e LIQUIBASE_CUSTOM_LOG_DATA_FILE="/liquibase/changelog/demo.yml"
--env LIQUIBASE_CUSTOM_LOG_DATA_FILE="/liquibase/changelog/demo.yml"

Note: Be aware the syntax requires a single dash for -e and a double dash for --env.

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:

For example, a command line argument’s configuration value will be used even if the environment variable for the same configuration value was set. This is because the command line argument is higher in the precedence list than an environment variable.

The following chart explicitly defines this behavior:

Location Behavior
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 (JAVA_OPTS Environment Variable)

 Override OS environment variables and configuration data
OS environment variables Override configuration data
Configuration data, such as the Liquibase properties file, piped standard input, or defaults files Does not override any values

Naming conventions

Liquibase environment variables include:

  • All the GlobalConfiguration settings: Liquibase_DATABASE_CHANGELOG_TABLE_NAME, Liquibase_SCHEMA_NAME, and others.
  • All the LiquibaseProConfiguration properties: Liquibase_LICENSE_KEY, Liquibase_PRO_MARK_UNUSED_NOT_DROPPED, Liquibase_PRO_SYNONYMS_DROP_PUBLIC, Liquibase_PRO_SQL_INLINE.

Security

Liquibase environment variables are READ ONLY. Liquibase never changes the value of an environment variable.

Related links