changelog Property Substitution

Liquibase allows 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

Liquibase allows you to use different ways to can set property values. Liquibase assigns these values in the order specified below:

Passed as a attribute 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.
As an environment variable.
As a CLI attribute if executed from the command line.
In the liquibase.properties file if used or executed from the command line. See the Creating and configuring a liquibase.properties file for more information.
In the parameters block (property element of the DATABASECHANGELOG table itself.

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

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`	Name of the parameter. Required if `file` is not set
`value`	Value of the of the property. required if `file` is not set
`file`	Name of the file the properties shall be loaded from. It will create a property for all properties in the file. The content of the file has to follow the java properties file format
`context`	Contexts the property is valid in. Expected as 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. Defines whether the property is global or limited to the actual DATABASECHANGELOG. Given as "true" or "false".

XML Example

<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"
	xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog 
		http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.8.xsd
		http://www.liquibase.org/xml/ns/dbchangelog-ext 
		http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.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>

YAML Example

databaseChangeLog:
	-  property:
		dbms:  oracle,postgresql
		name:  clob.type
		value:  clob
	-  property:
		dbms:  mysql
		name:  clob.type
		value:  longtext
	-  property:
		name:  table.name
		value:  tableA
	-  changeSet:
		id:  1
		author:  joe
		changes:
		-  createTable:
			tableName:  ${table.name}
			columns:
			-  column:
				name:  id
				type:  int
			-  column:
				name:  ${column1.name}
				type:  "${clob.type}
				defaultValue:  a  string  with  an  ${undefined.param}  param  against  ${dbNote}
			-  column:
				name:  ${column2.name}
				type:  int

JSON Example

{
	"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-3.8.xsd
		http://www.liquibase.org/xml/ns/dbchangelog-ext
		http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd"
	}
}