property-substitution-enabled

Last published July 28, 2025

--property-substitution-enabled is a command argument specific to checks run that allows you to determine when property substitution occurs in a changelog. You can change the default timing of property expansion in your changesets. This argument is for the whole of checks run, not a specific Policy check.

When --property-substitution-enabled is true, the checks run command evaluates the changeset after Liquibase replaces the property token, ${token}, with a value. When --property-substitution-enabled is false, the checks run command evaluates the changeset before Liquibase replaces the property token, ${token}, with a value. Learn more here: Substituting Properties in Changelogs.

Uses

For example, consider a stored procedure that you want to modify depending on your environment, which you configure using Contexts. You can use the --property-substitution-enabled parameter on checks run to dynamically modify your SQL.

In this example, Liquibase replaces ${prop} with @uat_db within changesets where the UAT context is active and @prod_db within changesets where the PROD context is active:

<property name="prop" value="@uat_db" context="UAT"/> <property name="prop" value="@prod_db" context="PROD"/>

Notice ${prop} in the following example. This is the name of the example property:

SELECT * FROM my_table${prop} WHERE column1 > column2;

Based on the value of --property-substitution-enabled, Liquibase behaves in one of two ways:

If --property-substitution-enabled=true, the checks run command sees the value of the property substitution (which could be the string @uat_db or the string @prod_db):

SELECT * FROM my_table@uat_db WHERE column1 > column2;

If --property-substitution-enabled=false, the checks run command sees the token string:

SELECT * FROM my_table${prop} WHERE column1 > column2;

Syntax

You can set this parameter in the following ways:

Option	Syntax
Liquibase properties file	liquibase.propertySubstitutionEnabled: <true\|false>
Command flow file argument (example)	stages: Default: actions: - type: liquibase command: checks run cmdArgs: { property-substitution-enabled: "<true\|false>" }
Command CLI parameter	liquibase checks run --property-substitution-enabled=<true\|false>
JVM system property (JAVA_OPTS Environment Variable)	JAVA_OPTS=-Dliquibase.propertySubstitutionEnabled=<true\|false>
Liquibase Environment Variables	LIQUIBASE_PROPERTY_SUBSTITUTION_ENABLED=<TRUE\|FALSE>

For more information, see Working with Command Parameters.