This is a Story about Control: context-filter, label-filter

LIQUIBASE RELEASE: VERSION 4.16.0

Suggested soundtrack: Control Janet Jackson*

TL;DR

1. If you are already using Contexts and Labels successfully, keep calm and Database DevOps on. Everything you are currently doing will continue to work. 
2. Liquibase has always had a way to "tag" and then "filter" on those tags to control which changesets are considered for execution. But we used the same words for both the tagging and the filtering settings which was confusing. 
3. We're fixing that by allowing users to be explicit on which is the "filter" half by adding the word "filter" into that setting. 

“I want to make my own decisions” – the changeset author

If you are the author of a changeset and want to control the filter logic, add a contextFilter attribute to your changeset defining the exact conditions under which it should run. Then specify –contexts argument string to be considered at runtime.

I am doing a remix of a classic here – updating Nathan Voxland’s examples from “Understanding When to Use Contexts vs. Labels”

…you might want to use a combination of features (shopping_cart vs. account_mgmt), bundles (pro vs. basic), and customers (acme vs. bigco).

Contexts allow the changeset author to specify the expression in the changeset. Developers can create the changeset as <changeSet id=”1” author=”example” contextFilter=”pro AND shopping_cart”> and the deployment manager simply “tags” the environment at runtime with liquibase update --contexts=pro,shopping_cart,bigco. But if they use --contexts=pro the changeset doesn’t run, because the AND logic set by the changeset author in the contextFilter argument.

the changeset doesn’t run, because the AND logic set by the changeset author in the contextFilter argument.

NOTE: If you have previously used context instead of contextFilter to define the expression in a changeset, it will continue to work.

Context Documentation

“I wanna be the one in control!” – the deployment manager

For labels, the power of the filter logic sits with the deployment manager. If you need to define this logic at runtime instead, add a label-filter as an argument when calling Liquibase. Then add the labels attribute string to your changeset.

The changeset author “tags” the changesets like

<changeSet id=”1” author=”example” labels=”pro, shipping_cart”> 

and this time the deployment manager runs

liquibase update --label-filter=”pro and (shopping_cart or account_mgmt)”

But if they run liquibase update --label-filter=”pro and shopping_cart and account_mgmt” the changeset doesn’t get applied because of the AND logic defined by the deployment manager in the label-filter argument.

NOTE: If you have previously been using --labels instead of --label-filter to define the expression in a changeset, it will continue to work.

Labels Documentation

Need Help?

As always, Pro customers, please don’t hesitate to reach out to support@liquibase.com.

Community users, drop a question in the Liquibase Forum. If you think something isn’t working right or have a way to make Liquibase even better, submit a GitHub Issue or PR.

I also HIGHLY recommend the Liquibase University “Managing Liquibase Changelogs” course. It’s completely FREE and has a great section all about changeset metadata, including contexts and labels.

For detailed information check our Release Notes and Full Changelog.

*FOOTNOTE: The author of this blog would like to point out that the song here is from Miss Jackson’s 1986 Control album, not her 1989 Rhythm Nation album, thus making it fully safe from the recently reported Janet Jackson Rhythm Nation CVE.