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 4.4 and later can process configuration values from multiple sources, such as the Liquibase properties file, environment variables, and Java system 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.

Tip: For a list of all environment variables, see Liquibase Parameters .

Syntax

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.

Scope

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 searchPath.
  • Command options are specific to the command, such as url and changelogFile.

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_SEARCH_PATH 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:

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.

    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.

macOS/Linux/Unix

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

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

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:

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

For example, if you want the log-level=INFO property set for the DEV environment and log-level=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.

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

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

Related links