- Concept
- Version · 6.0
- Deliver
What is a Flow variable?
Last updated: August 12, 2026
You can define variables as key-value pairs to use in one or more stages of your Flow files. When you run the flow command, Liquibase substitutes the variable names for their values.
You can define variables in three ways:
As global variables in the flow file's header section
As stage variables within individual stages
Included in an external YAML file that you reference in the flow file's header section
In Liquibase 4.24.0+, flow files inherit variables from other flow files that you call on. This lets you pass variables through multiple nested layers of flow files.
Stage variables have the highest precedence, followed by included variables, then global variables, and then variables inherited from another flow file.
Command-line interface (CLI) variables take the highest precedence over other variable scopes in Liquibase.
For example, liquibase flow -DDB_HOST=prod-db.example.com will set the variable DB_HOST to prod-db.example.com no matter what the variable is set to in stage, include, or global commands.
Uses
You can define a variable once but reuse it many times in different situations in your flow file. This provides flexibility and reduces code duplication. For example, variables may be useful to efficiently run multiple kinds of commands that contain the same file, directory, or other string.
It is a best practice to use global variables for things that can apply to your whole flow file, and stage variables for things that only apply to specific stages. Included variables are best for things that apply to multiple flow files.
You can also check the values of variables by using Flow Conditionals to dynamically run code in your flow files.
In Liquibase 4.26.0+, you can specify a default variable value for Liquibase to use if it doesn't receive an explicit one. For example, you could use this to specify optional command arguments (such as contexts and labels) as NULL if not explicitly specified in your definition.
Syntax
Define variables
Variable definitions always use the syntax key: "value". You must specify quotation marks around the value.
You can define included variables in an external YAML file, in this case liquibase.flowvariables.yaml:
PROJECT_NAME: "MyFlowProject"
THIS_DATE: "2024-05-12T15-00-20"
You can define global variables at the top of your flow file, in this case liquibase.myflowfile.yaml:
globalVariables:
STATUS_FILE: "status.txt"
UPDATE_LOG: "update.log"
HISTORY_FILE: "history.txt"
You can define stage variables within a particular stage, in this case stage-status:
stages:
stage-status:
stageVariables:
STATUS_FILE: "status.txt"
Use variables
Variable calls in your flow files use the following syntax:
Included variables:
${NAMESPACE.VARIABLE_KEY}Global and stage variables:
${VARIABLE_KEY}
For example, we can run the status command in a flow file using included, global, and stage variables. In the following example, the included variables all have the namespace FLOW_VARS and reference variables we previously defined in the file liquibase.flowvariables.yaml:
include:
FLOW_VARS: liquibase.flowvariables.yaml
globalVariables:
DIRECTORY_NAME: "./${FLOW_VARS.PROJECT_NAME}_${FLOW_VARS.THIS_DATE}"
STATUS_FILE: "status.txt"
stages:
stage-status:
stageVariables:
VERBOSE_STATE: "true"
actions:
- type: liquibase
command: status
globalArgs: {output-file: "${DIRECTORY_NAME}/${STATUS_FILE}"}
cmdArgs: {verbose: "${VERBOSE_STATE}"}
Default values
In Liquibase 4.26.0 and later, you can give variables default values using the following syntax:
Example: VARIABLE_KEY: "${VARIABLE_KEY:-defaultValue}"
This is useful if you want to dynamically specify optional arguments for commands in your flow file. For example:
globalVariables:
VERBOSE_STATE: "${VERBOSE_STATE:-null}"
# Set the default value to null
stages:
stage-status:
stageVariables:
VERBOSE_STATE: "true"
# Set a value for this stage only
actions:
- type: liquibase
command: status
cmdArgs: {verbose: "${VERBOSE_STATE}"}
# This stage passes a non-null value to verboseState
other-stage:
actions:
- type: liquibase
command: status
cmdArgs: {verbose: "${VERBOSE_STATE}"}
# This stage doesn't define any stage variables
# Liquibase uses the definition from the global variable, which defaults to null
In the preceding example, VERBOSE_STATE is set to null by default as a global variable and is set to a non-null value as a stage variable. During stage-status, Liquibase passes the non-null value. During stage-other, VERBOSE_STATE is not defined as a stage variable, so Liquibase passes the global value, which is null. When Liquibase detects a null value in a global or command argument, it omits the entire argument at runtime.
Note: It's possible to define a variable without default values both globally and in a stage. In this design, you simply rely on the stage variable's higher precedence to control the value of the output in different situations. However, explicitly specifying default values can make the intended behavior of a flow file clearer to developers.
Default values can also be useful when you use them with Flow Conditionals. For example:
globalVariables:
UPDATE: "${UPDATE:-null}"
CHANGELOG_FILE: "${CHANGELOG_FILE:-simple-changelog.xml}"
stages:
someStage:
actions:
- type: liquibase
if: "UPDATE != null"
command: update
cmdArgs: {changelog-file: "${CHANGELOG_FILE}"}
In the preceding example, Liquibase checks whether the value of the global variable UPDATE is not null before executing the rest of the action.
Note: If you define a default value for a variable, the default is inherited by any nested flow files that call on the parent flow file. The default value also applies to the nested flow files.
Default values: nested property substitution
You can nest variables within each other, which allows you to specify dynamic variable names at runtime. This allows flexibility within flow files to set and pass global variables as part of another variable.
Example:
1. Set a global variable with a default value inside the flow file.
globalVariables:
SCHEMA: "${SCHEMA:-public}"
2. Pass that same variable into another global (or stage) variable.
globalVariables:
SCHEMA: "${SCHEMA:-public}"
DBURL: "jdbc:h2:file:./target/${SCHEMA}"
3. Place the global variable containing the original variable into a Flow stage.
stages:
Default:
actions:
#
#
- type: liquibase
command: update-sql
cmdArgs: {changelog-file: "changelogs/changelog.sql", url: "${DBURL}"}
In this example, the variables expand as follows:
${DBURL} → jdbc:h2:file:./target/${SCHEMA} → jdbc:h2:file:./target/public
Environment variables
You can substitute the values of environment variables in your flow file. The syntax is the same as substituting other variables. For example:
stages:
systemEnvars:
actions:
- type: shell
command: echo "Running Liquibase from ${LIQUIBASE_HOME}"
commandStuff:
actions:
- type: liquibase
command: update-sql
globalArgs: {changelog-file: "${LIQUIBASE_OUTPUT_FILE}"}
This lets you avoid manually updating information in your flow file, such as the path of the system environment variable LIQUIBASE_HOME, which could change if you later modify your installation directory.
Substituting environment variables may also be useful if you want to avoid modifying your flow file whenever you change the value of Liquibase parameters like LIQUIBASE_OUTPUT_FILE. Instead of defining and updating variables in your flow file, you can simply update the values of the external environment variables the flow file calls on. Then, when you run your flow file, Liquibase uses the new values without you ever having modified the flow file itself.
Command substitutions
In Liquibase 4.28.0 and later, you can also use variables in the command field of a flow file action. For example:
globalVariables:
MY_COMMAND: "status"
MY_CHANGELOG: "newChangelog.txt"
stages:
myStage:
actions:
- type: liquibase
command: ${MY_COMMAND}
cmdArgs: {changelog-file: "${MY_CHANGELOG}"}
The preceding example calls on a global variable from the command field. You can use the same syntax to call on environment variables instead.
Empty strings
You can specify the empty string as the value of a variable. For example, if you want to run all changesets in your changelog regardless of their contexts/labels:
stages:
default:
stageVariables:
LABEL_NAMES: ""
actions:
- type: liquibase
command: update
cmdArgs: {label-filter: "${LABEL_NAMES}"}
Property substitution with full YAML strings
In Liquibase 4.28.0 and later, you can also use variables to dynamically expand into full YAML strings during property substitution. The YAML strings you insert can also contain other variables, which can expand into more YAML strings.
For example, this may be useful if you want multiple stages of a single flow file to run a command, but you want to substitute different variables to modify that command in each stage of the flow file.
globalVariables:
COMMAND_ARGS: "changelog-file: './liquibase.${STAGE_CHANGELOG}.yaml'"
stages:
stage01:
# Set up vars for property substitution in THIS stage only
stageVariables:
STAGE_CHANGELOG: "stage01"
actions:
# Run the update command
- type: liquibase
command: update
cmdArgs: {"${COMMAND_ARGS}"}
# This expands to: cmdArgs: { changelog-file: './liquibase.${STAGE_CHANGELOG}.yaml'}
# which expands to: cmdArgs: { changelog-file: './liquibase.stage01.yaml'}
Example Flow file
liquibase.flowvariables.yaml
Defines variables that you can use in other flow files.
# List of variables
PROJNAME: "MyFlowProj"
THISDATE: "2022-11-28T15-00-20"
liquibase.flowfile.yaml
Includes command arguments, global arguments, and a referenced include file (YAML).
# Bring in and namespace an external file with yaml 'key: val' pairs for use in this file
include:
FLOWVARS: liquibase.flowvariables.yaml
# Set up some global variables for property substitution in ANY stage
globalVariables:
DIRNAME: "./${FLOWVARS.PROJNAME}_${FLOWVARS.THISDATE}"
STATUSFILE: "status.txt"
UPDATELOG: "update.log"
HISTORYFILE: "history.txt"
# Start of the stages.
stages:
# A prep stage. There can be more than one stage if desired.
stage-prep:
actions:
- type: shell
command: bash -c "mkdir -p ${DIRNAME}"
# Another stage.
stage-dowork:
# set up vars for property substitution in THIS stage only
stageVariables:
VERBOSESTATE: TRUE
actions:
# Do a validate command
- type: liquibase
command: validate
# Tell me what is pending a deployment
- type: liquibase
command: status
globalArgs:
outputfile: "${DIRNAME}/${STATUSFILE}"
showbanner: false
cmdArgs: {verbose: "${VERBOSESTATE}"}
# Policy Checks for changelog
- type: liquibase
command: checks run
cmdArgs: {checks-scope: changelog}
# Run update
- type: liquibase
command: update
# Policy Checks for database
- type: liquibase
command: checks run
cmdArgs: {checks-scope: database}
# Create a history file
- type: liquibase
command: history
globalArgs: {outputfile: "${DIRNAME}/${HISTORYFILE}"}