label-filter

Uses

In your changelog, you can specify only a simple list of labels to apply to the changeset. For example, labels="v.0.1, v.1.0". At runtime, you can specify a complex expression with the labels that you want to execute. For example, --label-filter="!v.0.1" or --label-filter="v.1.0 or (v.1.1 and v.1.2)".

Specify a label using @ in addition to AND, OR, !, and parentheses. Parentheses are used for grouping. Learn more about the labelFilter logic at this blog post.

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.

Example: If you run the liquibase update --label-filter=1.0 command, it will deploy all changesets with the label 1.0 and all changesets without any label or with label="". If you run liquibase update, it will deploy all changesets, whether they have labels or not.

The @ operator

The @ symbol is used in the --label-filter argument at runtime to force strict label matching. By default, changesets without labels are always executed. Using @ ensures that only changesets with the specified label are executed.

Given these changesets

--changeset postgres:1 labels:hotfix CREATE TABLE public.Persons1 (PersonID int); --changeset postgres:2 labels:hotfix CREATE TABLE public.Persons2 (PersonID int); --changeset postgres:3 labels:release CREATE TABLE public.Persons3 (PersonID int); --changeset postgres:4 CREATE TABLE public.Persons4 (PersonID int);

Running liquibase changelog-sync --label-filter="@hotfix" executes only changesets 1 and 2. Changeset 3 (labeled release) and changeset 4 (no label) are both excluded.

Additional examples

• --label-filter="@test"

• --label-filter="!v.0.1"

• --label-filter="v.1.0 and v.1.1"

• --label-filter="v.1.0 or v.1.1"

• --label-filter="!v.1.0 and !v.1.1"

Using "," to separate labels works like an OR operation (a comma is an alias for OR). For example:

• --label-filter="v.1.0, v.1.1" is the same as --label-filter="v.1.0 OR v.1.1"

• --label-filter="v.0.1, v.1.0 and v.1.1" is the same as --label-filter="(v.0.1) OR (v.1.0 and v.1.1)"

Usage examples

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:

• --label-filter=1.0 to deploy the 1.0 changesets or --label-filter=shopping_cart to deploy the changesets related to the shopping cart.

• --label-filter="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.

• --label-filter="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.

You can see an example of running the update command with complex --label-filter statements:

liquibase --output-file=update.txt update --changelog-file=changelog.xml --label-filter="1.0 or (1.1 and !shopping_cart)"

Related filter arguments

Liquibase also provides filter arguments for other changeset attributes: context-filter, teams-filter, releases-filter, keywords-filter, and conditions-filter. The teams, releases, keywords, and conditions filters use straight string matching and require Liquibase Secure 5.2.2 or later. As of Secure 6.0, they also support the @ strict-matching operator.

Syntax

You can set this parameter in the following ways: