What are Liquibase environment variables?

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.

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:

environment-variables 414x350

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.

What are Liquibase environment variables? - Liquibase