Labels

Labels are tags that you can add to changesets to control which changeset will be executed in any migration run. Labels control whether a changeset is executed depending on runtime settings. Any string can be used for the label name, and it is case-insensitive.

Uses

Liquibase allows you to run the --labels attribute to determine which changesets in the changelog to evaluate based on its label.

  • In your changelog, you can specify only a simple list of labels to apply to the changeset. For example, labels="qa, acme_inc".
  • At runtime, you can specify a complex expression with the labels that you want to execute. For example, --labels="!acme_inc" or --labels="pro or (free and beta)".

How to work with labels

It is best practice to enumerate your changesets or describe what a changeset is used for. An example of labels indicating the version or a specific feature can be "1.0" or "shopping_cart". In this case, labels will allow you to run changes with:

  • --labels=1.0 to deploy the 1.0 changesets or --labels=shopping_cart to deploy the changesets related to the shopping cart.
  • --labels="1.0 or (1.1 and shopping_cart)" to deploy the 1.0 changesets and only the 1.1. features related to the shopping cart.
  • --labels="1.0 or (1.1 and !shopping_cart)" to deploy the 1.0 changesets and the 1.1. features that are not related to the shopping cart.
liquibase --changeLogFile=changelog.xml --outputFile=updateSQL.txt --labels=1.0 updateSQL

An example of the changelog file with labels:

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
        <databaseChangeLog  xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:pro="http://www.liquibase.org/xml/ns/pro"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
        http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.6.xsd
        http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-3.8.xsd">
        
		<changeSet  author="Liquibase User"    id="1::createTableforSynonym-proschema"  labels="1.0"  objectQuotingStrategy="QUOTE_ALL_OBJECTS">
        <createTable  schemaName="proschema"  tableName="primary_table">
        <column  name="name"  type="CHAR(20)"/>
        </createTable>
        </changeSet>
        
		<changeSet  author="Liquibase Pro User"  id="2::createTableforView-proschema"  labels="1.1"  objectQuotingStrategy="QUOTE_ALL_OBJECTS">
        <createTable  schemaName="proschema"  tableName="account">
        <column  name="acct_num"  type="NUMBER(20,0)"/>
        <column  name="amoount"  type="NUMBER(10,2)"/>
        </createTable>
        </changeSet>
        </databaseChangeLog>