Substituting Properties in Changelogs
Liquibase allows a dynamic substitution of properties in your changelog. The tokens to replace in your changelog are described using the ${property-name}
syntax.
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 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. See Liquibase Environment Variables for more information.
- As a CLI attribute if executed from the command line.
- In the Liquibase properties file if used or run from the command line. For more information, see Specifying Properties in a Connection Profile.
- In the parameters block (property element of the DATABASECHANGELOG table 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 _
.
Note: If you do not want to replace an otherwise matching ${property-name}
expression, add :
to the beginning of the expression. An expression of ${: property-name}
will always be converted to ${property-name}
regardless of whether property-name
is defined.
Nested properties
Name | Description | Required for | Supports | Multiple allowed? |
---|---|---|---|---|
<property>
|
Defined before changesets in the changelog | Substituting portions of a changeset during runtime | All supported changeset tokens | No. Property names are unique and can only be set one. |
Available attributes
Attribute | Description |
---|---|
name
|
The name of the parameter. Required if file is not set |
value
|
The value of the property. Required if file is not set |
file
|
The name of the file from which the properties should be loaded. It will create a property for all properties in the file. The content of the file must follow the java properties file format. |
context
|
Contexts in which the property is valid. Expected as a comma-separated list. |
dbms
|
The type of a database which that property is to be used. When the migration step is running, it checks the database type against this
attribute. Valid database type names are listed on the supported databases page. It is possible to list multiple databases separated by commas.
You can also specify that a changeset is not applicable to a particular database type by prefixing with ! . The keywords all and none are
also available. |
global
|
Boolean. The attribute defines whether the property is global or limited to the actual DATABASECHANGELOG. The default value is true . |

--liquibase formatted sql
--changeset example:1
CREATE TABLE ${schema.name}.person
( id int primary key,
first_name varchar(50) NOT NULL,
last_name varchar(50) NOT NULL
)
Using the example changelog and running the liquibase update-sql
command with the configured environment variable schema.name=dev_schema
, you will receive the following SQL output: CREATE TABLE dev_schema.person
.

<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
xmlns:pro="http://www.liquibase.org/xml/ns/pro"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">
<property name="clob.type" value="clob" dbms="oracle,postgresql"/>
<property name="clob.type" value="longtext" dbms="mysql"/>
<property name="table.name" value="tableA"/>
<changeSet id="1" author="joe">
<createTable tableName="${table.name}">
<column name="id" type="int"/>
<column name="${column1.name}" type="${clob.type}"/>
<column name="${column2.name}" type="int"/>
</createTable>
</changeSet>
</databaseChangeLog>

databaseChangeLog:
- property:
dbms: oracle,postgresql
name: clob.type
value: clob
- property:
dbms: mysql,mariadb
name: clob.type
value: longtext
- property:
name: table.name
value: tableA
- changeSet:
id: 1
author: joe
dbms: mariadb
changes:
- createTable:
tableName: ${table.name}
columns:
- column:
name: id
type: int
- column:
name: Column1
type: ${clob.type}
- column:
name: Column2
type: int

{
"databaseChangeLog": {
"property": [
{
"_name": "clob.type",
"_value": "clob",
"_dbms": "oracle,postgresql"
},
{
"_name": "clob.type",
"_value": "longtext",
"_dbms": "mysql"
},
{
"_name": "table.name",
"_value": "tableA"
}
],
"changeSet": {
"createTable": {
"column": [
{
"_name": "id",
"_type": "int"
},
{
"_name": "${column1.name}",
"_type": "${clob.type}"
},
{
"_name": "${column2.name}",
"_type": "int"
}
],
"_tableName": "${table.name}"
},
"_id": "1",
"_author": "joe"
},
"_xmlns": "http://www.liquibase.org/xml/ns/dbchangelog",
"_xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
"_xmlns:ext": "http://www.liquibase.org/xml/ns/dbchangelog-ext",
"_xsi:schemaLocation": "http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.8.0.xsd
http://www.liquibase.org/xml/ns/dbchangelog-ext
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd"
}
}