property-substitution-enabled

--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.

Related links