Uses

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

The --keywords-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 keywords 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 --keywords-filter, all changesets run whether they have a keywords attribute or not.

The @ operator

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

Given these changesets:

--changeset your.name:1 keywords:pii CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY); --changeset your.name:2 keywords:pii CREATE TABLE t2 (id INT NOT NULL PRIMARY KEY); --changeset your.name:3 keywords:audit 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 --keywords-filter="@pii" executes only changesets 1 and 2. Changeset 3 (keywords:audit) and changeset 4 (no keywords attribute) are both excluded.

Supported commands

You can use --keywords-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 keywords:schema-init 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 keywords:hotfix 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 keywords:compliance 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 --keywords-filter=hotfix deploys changeset 2 (products) and changeset 4 (app_config).

• liquibase update --keywords-filter="schema-init,compliance" deploys changesets 1, 3, and 4.

• liquibase update --keywords-filter=inventory deploys only changeset 4.

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

Syntax

You can set this parameter in the following ways: