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, 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.
Using Liquibase Environment Variables
Tip: To see the list of all environment variables, check Liquibase Parameters.
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.
- Do not use spaces within values.
- Use uppercase letters.
- Use the prefix of
Note: For default files, use the prefix of
liquibase.. However, when running arguments in the CLI, you can drop the
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
- Command options are specific to the command, such as
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_PATHconfigures a global option.
LIQUIBASE_COMMAND_USERNAMEsets the username to use across all commands.
LIQUIBASE_COMMAND_UPDATE_USERNAMEsets the username just for the
Setting Environment Variables
To set the Liquibase environment variables, choose your operating system:
- In your Windows search box, type
envand select the Edit the System Environment option in the Control Panel.
- In the Advanced tab, select Environment Variables.
- In the Edit environment variable window, select New, and then add the variable name and value you need.
- 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.
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.
export variable_name=value command does not permanently update your value after the termination of the session. To permanently update the value, edit your
~/.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
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 (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.
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
LIQUIBASE_SCHEMA_NAME, and others.
- All the
- All the
If you use Liquibase environment variables, Liquibase only reads values from environment variables without writing any of them.