• Task
  • Version · 6.0
  • Deliver

Add a globalVariable to your Flow file

Last updated: August 11, 2026

Available in Liquibase Secure 5.1 and later, globalVariables make Flow files configurable, maintainable, and portable by keeping all variable definitions and Liquibase properties in one place at the flow level rather than scattered throughout individual stages or relying on external configuration sources. Setting required properties like url and changelog-file in the globalVariables section of your Flow file makes it self-contained and portable; anyone can run it immediately without needing to configure external properties files or environment variables. This is especially valuable when you have multiple flow files targeting different databases or changelogs, when sharing workflows with team members or running them in CI/CD pipelines, or when you want the flow file itself to document which database and changelog it operates on clearly. While properties files are still helpful for global defaults and local developer preferences, using globalVariables turns your flow files into complete, executable workflow definitions that can be version-controlled and shared as single artifacts.

Before you begin

Create a Flow file

Procedure

1

Add a globalVariables section at the top of your flow file:

loading
2

Define your globalVariables

Replace each globalVariable placeholder with the real file name or location. Example Replace the URL placeholder with your unique URL: LIQUIBASE_COMMAND_URL: "jdbc:snowflake://account123.us-east-1.aws.snowflakecomputing.com/?warehouse=MY_WAREHOUSE&db=MY_DATABASE&schema=MY_SCHEMA&user=myuser" Replace the Changelog placeholder with your unique Changelog file name: LIQUIBASE_COMMAND_CHANGELOG_FILE: "Changelogs/changelog.main.xml"

3

Optional: Use variable substitution syntax

If you want to reference environment variables with default fallback values, use the substitution syntax "${VARIABLE_NAME:-default_value}".

How it works:

  • Liquibase first checks if an environment variable with that name exists

  • If the environment variable exists: Liquibase uses that value

  • If the environment variable does NOT exist: Liquibase uses the default value after the :-

Example: globalVariables: LB_ENVIRONMENT: "${LB_ENVIRONMENT:-PROD}"

In this example:

  • If you set export LB_ENVIRONMENT=DEV before running Liquibase, LB_ENVIRONMENT will be DEV

  • If you don't set any environment variable, LB_ENVIRONMENT will default to PROD

When to use this: This gives you the flexibility to use the same Flow file across different environments (dev, test, prod) by overriding values with environment variables when needed, while still maintaining sensible defaults.

Results

When you run the flow file with globalVariables configured:

  • Your Flow file becomes self-contained and valid.

    Previously, you had to configure URL and changelog file in a separate properties file, environment variables, or CLI arguments before the Flow file would validate. Now you can set them directly in the Flow file itself.

  • The liquibase flow command will succeed.

    The flow validation that runs behind the scenes will now pass because Liquibase can find the required URL and changelog file properties within the Flow file.

  • The Flow file values take precedence. Because of the property hierarchy ("properties closest to the operation win"), the values you set in the Flow file will override any values set elsewhere—even if you have the same properties configured in:

    • CLI arguments

    • Environment variables

    • liquibase.properties

PreviousWhat are advanced flow files?NextUse flow files with Spring