Reference
Version · 6.0
Change Automation Reference

labels

Last updated: September 29, 2026

Labels are tags you add to changesets in your changelog to describe what each changeset is for, such as a particular feature or version. You can specify a label name as any case-insensitive string. At runtime, you can control which labeled changesets a command runs using the label-filter argument.

Labels work best when the changeset author can simply enumerate or describe what a changeset is used for. The complexity of deciding which changesets to run is left to the deployment manager or person executing the changesets, who selects them at runtime with a filter expression. Labels are similar to contexts, which you can use to specify other tags, such as development environments.

Uses

You can typically use labels to:

Manage and track your deployments.
Apply complex logic to filter the changesets eligible for deployment.
Mark changesets based on features and then selectively apply those features at the execution time instead of using version control branches.
Use different languages for marking changesets. For example, you can mark your changesets both with Spanish and English.
Assign ticket numbers to particular changesets to track and identify their purpose, such as JIRA ticket numbers

include and includeAll labels

You can specify the labels attribute in include and includeAll tags. If specified, the given label is added to all changesets in the included file(s).

Syntax

--liquibase formatted sql

--changeset your.name:1 labels:1.0,prod,shopping_cart
CREATE TABLE person (firstname VARCHAR(255) NULL);

--changeset your.name:2 labels:2.0,test
ALTER TABLE person ADD address VARCHAR(255) NULL;

--changeset your.name:3 labels:shopping_cart
ALTER TABLE person ADD favorite_color VARCHAR(255) NULL;

--changeset your.name:4
CREATE TABLE no_label (no_label_col VARCHAR(255) NULL);

{
    "databaseChangeLog": [
        {
            "changeSet": {
                "id": "1",
                "author": "your.name",
                "labels": "1.0,prod,shopping_cart",
                "changes": [
                    {
                        "createTable": {
                            "tableName": "person",
                            "columns": [
                                {
                                    "column": {
                                        "name": "firstname",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "changeSet": {
                "id": "2",
                "author": "your.name",
                "labels": "2.0,test",
                "changes": [
                    {
                        "addColumn": {
                            "tableName": "person",
                            "columns": [
                                {
                                    "column": {
                                        "name": "address",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "changeSet": {
                "id": "3",
                "author": "your.name",
                "labels": "shopping_cart",
                "changes": [
                    {
                        "addColumn": {
                            "tableName": "person",
                            "columns": [
                                {
                                    "column": {
                                        "name": "favorite_color",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "changeSet": {
                "id": "4",
                "author": "your.name",
                "changes": [
                    {
                        "createTable": {
                            "tableName": "no_label",
                            "columns": [
                                {
                                    "column": {
                                        "name": "no_label_col",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: your.name
      labels: '1.0,prod,shopping_cart'
      changes:
        - createTable:
            tableName: person
            columns:
              - column:
                  name: firstname
                  type: varchar(255)
  - changeSet:
      id: '2'
      author: your.name
      labels: '2.0,test'
      changes:
        - addColumn:
            tableName: person
            columns:
              - column:
                  name: address
                  type: varchar(255)
  - changeSet:
      id: '3'
      author: your.name
      labels: 'shopping_cart'
      changes:
        - addColumn:
            tableName: person
            columns:
              - column:
                  name: favorite_color
                  type: varchar(255)
  - changeSet:
      id: '4'
      author: your.name
      changes:
        - createTable:
            tableName: no_label
            columns:
              - column:
                  name: no_label_col
                  type: varchar(255)

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<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">

    <changeSet  author="your.name"  id="1"  labels="1.0,prod,shopping_cart">
        <createTable  tableName="person">
            <column  name="firstname"  type="VARCHAR(255)"/>
        </createTable>
    </changeSet>

    <changeSet  author="your.name"  id="2"  labels="2.0,test">
        <addColumn  tableName="person">
            <column  name="address"  type="VARCHAR(255)"/>
        </addColumn>
    </changeSet>

    <changeSet  author="your.name"  id="3"  labels="shopping_cart">
        <addColumn  tableName="person">
            <column  name="favorite_color"  type="VARCHAR(255)"/>
        </addColumn>
    </changeSet>

    <changeSet  author="your.name"  id="4">
        <createTable  tableName="no_label">
            <column  name="no_label_col"  type="VARCHAR(255)"/>
        </createTable>
    </changeSet>

</databaseChangeLog>

--liquibase formatted sql

--changeset your.name:1 labels:1.0,prod,shopping_cart
CREATE TABLE person (firstname VARCHAR(255) NULL);

--changeset your.name:2 labels:2.0,test
ALTER TABLE person ADD address VARCHAR(255) NULL;

--changeset your.name:3 labels:shopping_cart
ALTER TABLE person ADD favorite_color VARCHAR(255) NULL;

--changeset your.name:4
CREATE TABLE no_label (no_label_col VARCHAR(255) NULL);

{
    "databaseChangeLog": [
        {
            "changeSet": {
                "id": "1",
                "author": "your.name",
                "labels": "1.0,prod,shopping_cart",
                "changes": [
                    {
                        "createTable": {
                            "tableName": "person",
                            "columns": [
                                {
                                    "column": {
                                        "name": "firstname",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "changeSet": {
                "id": "2",
                "author": "your.name",
                "labels": "2.0,test",
                "changes": [
                    {
                        "addColumn": {
                            "tableName": "person",
                            "columns": [
                                {
                                    "column": {
                                        "name": "address",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "changeSet": {
                "id": "3",
                "author": "your.name",
                "labels": "shopping_cart",
                "changes": [
                    {
                        "addColumn": {
                            "tableName": "person",
                            "columns": [
                                {
                                    "column": {
                                        "name": "favorite_color",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        {
            "changeSet": {
                "id": "4",
                "author": "your.name",
                "changes": [
                    {
                        "createTable": {
                            "tableName": "no_label",
                            "columns": [
                                {
                                    "column": {
                                        "name": "no_label_col",
                                        "type": "VARCHAR(255)"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

databaseChangeLog:
  - changeSet:
      id: '1'
      author: your.name
      labels: '1.0,prod,shopping_cart'
      changes:
        - createTable:
            tableName: person
            columns:
              - column:
                  name: firstname
                  type: varchar(255)
  - changeSet:
      id: '2'
      author: your.name
      labels: '2.0,test'
      changes:
        - addColumn:
            tableName: person
            columns:
              - column:
                  name: address
                  type: varchar(255)
  - changeSet:
      id: '3'
      author: your.name
      labels: 'shopping_cart'
      changes:
        - addColumn:
            tableName: person
            columns:
              - column:
                  name: favorite_color
                  type: varchar(255)
  - changeSet:
      id: '4'
      author: your.name
      changes:
        - createTable:
            tableName: no_label
            columns:
              - column:
                  name: no_label_col
                  type: varchar(255)

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<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">

    <changeSet  author="your.name"  id="1"  labels="1.0,prod,shopping_cart">
        <createTable  tableName="person">
            <column  name="firstname"  type="VARCHAR(255)"/>
        </createTable>
    </changeSet>

    <changeSet  author="your.name"  id="2"  labels="2.0,test">
        <addColumn  tableName="person">
            <column  name="address"  type="VARCHAR(255)"/>
        </addColumn>
    </changeSet>

    <changeSet  author="your.name"  id="3"  labels="shopping_cart">
        <addColumn  tableName="person">
            <column  name="favorite_color"  type="VARCHAR(255)"/>
        </addColumn>
    </changeSet>

    <changeSet  author="your.name"  id="4">
        <createTable  tableName="no_label">
            <column  name="no_label_col"  type="VARCHAR(255)"/>
        </createTable>
    </changeSet>

</databaseChangeLog>

Filtering labels

At runtime, use the label-filter argument to determine which changesets run based on their labels. The label filter is a logical expression that supports AND, OR, !, parentheses, and the @ strict-matching operator. See label-filter for the full expression syntax and examples.

If a changeset doesn't have a label, it will always run, even when a label filter is specified, unless the filter uses the @ operator. If you make a deployment without specifying any labels in the label filter, all changesets will run.

Liquibase also provides filter arguments for other changeset attributes. Each argument filters on its own attribute:

Argument	Filters on	Matching
`--label-filter=<string>`	`labels`	Logical expressions: `AND`, `OR`, `!`, parentheses, `@`
`--context-filter=<string>`	`contexts`	Comma-separated list. Expression logic is set on the changeset.
`--teams-filter=<string>`	`teams`	Straight string match. Comma-separated list matches any value. As of Secure 6.0, supports the @ strict-matching operator.
`--releases-filter=<string>`	`releases`	Straight string match. Comma-separated list matches any value. As of Secure 6.0, supports the @ strict-matching operator.
`--keywords-filter=<string>`	`keywords`	Straight string match. Comma-separated list matches any value. As of Secure 6.0, supports the @ strict-matching operator.
`--conditions-filter=<string>`	`conditions`	Straight string match. Comma-separated list matches any value. As of Secure 6.0, supports the @ strict-matching operator.

Note: The teams, releases, keywords, and conditions attributes and their filters require Liquibase Secure 5.2.2 or later.

PreviousLabel-filter NextLogicalFilePath

labels

Uses

include and includeAll labels

Syntax

SQL

JSON

YAML

XML

Filtering labels