releases-filter

Uses

Pass --releases-filter with one value or a comma-separated list of values. A changeset matches when any value in its releases attribute equals any value in the filter. Matching is a straight string comparison and is fully case-insensitive on both sides. For example, releases="V1.0" matches --releases-filter=v1.0.

The --releases-filter argument does not support the full logical expressions of label-filter and context-filter. There is no AND, OR, !, or parenthetical grouping. As of Liquibase Secure 6.0, it does support the @ strict-matching operator, described below. A comma-separated list matches changesets that have any of the listed values. Liquibase stores the attribute value exactly as you authored it and only splits, trims, and lowercases the values when the filter is evaluated.

If a changeset does not have a releases attribute, it always runs, even when a filter is specified, unless the filter uses the @ operator. This matches the behavior of labels and contexts. If you run a command without --releases-filter, all changesets run whether they have a releases attribute or not.

The @ operator

The @ symbol is used in the --releases-filter argument at runtime to force strict matching. By default, changesets without a releases value are always executed. Using @ ensures that only changesets with the specified releases value are executed. The @ operator requires Liquibase Secure 6.0 or later.

Given these changesets:

--changeset your.name:1 releases:v1.3.5 CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY); --changeset your.name:2 releases:v1.3.5 CREATE TABLE t2 (id INT NOT NULL PRIMARY KEY); --changeset your.name:3 releases:v2.0.0 CREATE TABLE t3 (id INT NOT NULL PRIMARY KEY); --changeset your.name:4 CREATE TABLE t4 (id INT NOT NULL PRIMARY KEY);

Running liquibase update --releases-filter="@v1.3.5" executes only changesets 1 and 2. Changeset 3 (releases:v2.0.0) and changeset 4 (no releases attribute) are both excluded.

Supported commands

You can use --releases-filter with the commands that execute or evaluate changesets:

• Update commands: update, update-sql, update-count, update-to-tag, update-testing-rollback

• Rollback commands: rollback, rollback-sql, rollback-count, rollback-count-sql, rollback-to-date, rollback-to-date-sql, future-rollback-sql, future-rollback-count-sql, future-rollback-from-tag-sql

• Utility and tracking commands: changelog-sync, changelog-sync-sql, changelog-sync-to-tag, status, mark-next-changeset-ran, mark-next-changeset-ran-sql

• Policy checks: checks run

Commands that do not execute changesets, such as diff, generate-changelog, snapshot, validate, and tag, do not accept the filter arguments. Commands that generate operation reports also record the filter values you used in the report.

Examples

Given these changesets:

--liquibase formatted sql --changeset your.name:1-create-employees releases:v1.0,v1.1 CREATE TABLE employees (id INT NOT NULL PRIMARY KEY, name VARCHAR(100) NOT NULL, department VARCHAR(50)); --rollback DROP TABLE employees; --changeset your.name:2-create-products releases:v1.1 CREATE TABLE products (id INT NOT NULL PRIMARY KEY, name VARCHAR(100) NOT NULL, price DECIMAL(10,2)); --rollback DROP TABLE products; --changeset your.name:3-create-audit-log releases:v2.0 CREATE TABLE audit_log (id INT NOT NULL PRIMARY KEY, action VARCHAR(255), performed_at TIMESTAMP); --rollback DROP TABLE audit_log; --changeset your.name:4-create-app-config CREATE TABLE app_config (id INT NOT NULL PRIMARY KEY, setting_name VARCHAR(100)); --rollback DROP TABLE app_config;

• liquibase update --releases-filter=v1.1 deploys changesets 1, 2, and 4.

• liquibase update --releases-filter=v2.0 deploys changeset 3 (audit_log) and changeset 4 (app_config).

• liquibase update --releases-filter=v3.0 deploys only changeset 4.

You can also roll back by the same dimension. For example, liquibase rollback-count 1 --releases-filter=v1.1 rolls back the most recently deployed changeset whose releases attribute matches.

Syntax

You can set this parameter in the following ways: