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.
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
andsearchPath
. - Command options are specific to the command, such as
url
orhubProjectID
.
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 theupdate
command.
Setting Environment Variables
To set the Liquibase environment variables, choose your operating system:
Windows
- In your Windows search box, type
env
and 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.
Example: LIQUIBASE_LICENSE_KEY
yj4v59bfdgj389btc4wg
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.
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_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.