What is property substitution?

Uses

By substituting values for replacement tokens in the format of ${property-name}, you can use the same changesets to reflect small environmental changes.

For example, your tablespace name in Oracle may differ from environment to environment, but you want to only write one create table changeset that can be used in all of your environments.

Using property substitution in your changelog

You can set property values in Liquibase in several ways. Liquibase assigns these values in the following order:

• As an attribute passed to your Liquibase runner. See the Ant, Maven, or Servlet Listener documentation for more information on how to pass them.

• As a JVM system property. See JAVA_OPTS Environment Variable for more information.

• As an environment variable.

• As a CLI attribute, if executed from the command line. Use the syntax liquibase <command.name> -D<property.name>=<property.value>. On Windows, surround the property name in quotation marks if it contains a dot. For example: -D"property.name"=value.

• In the parameters block (property element of the changelog file itself).

Once a property has been set, it cannot be changed. Also, only the first definition is used, others are skipped.

Note: If the content of ${property-name} does not match a property, it is left as-is and it is not removed. The supported format includes alphanumeric characters, +, -, . , and _.

Defining properties with contexts

You can define multiple values for the same property by associating each with a specific context. For example, the context-based TS_NAME property in the example changelog below resolves to DEV_TS when Liquibase runs with --context=DEV, which lets you safely use a single changelog across all environments.

Be sure to place <property> tags at the beginning of the changelog, before any <changeSet> definitions.

Example changelog

The following example combines all three kinds of property substitution in a single changelog:

• A dbms-based property (clob.type) whose value changes with the target database platform.

• A context-based property (TS_NAME) whose value changes with the deployment context, selected with --context.

• A plain property (table.name) that is the same in every environment.

The changeset references each property with the ${...} syntax. The XML, YAML, and SQL tabs include inline comments explaining each substitution. The JSON tab is shown without comments because JSON does not support them.