Liquibase Context & Label Filters Explained

Content updated September 2025

‍

Key Takeaways

• Liquibase now distinguishes between tagging and filtering with contextFilter and label-filter.
  
• Contexts let the changeset author define when a changeset runs (logic baked into the changeset).
  
• Labels let deployment managers control execution logic at runtime using the --label-filter argument.
  
• Backward compatibility is maintained: older context and --labels syntax will continue to work.
  
• Liquibase University offers free training on managing contexts and labels.

‍

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, Liquibase 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.

‍

Frequently Asked Questions

Q1: What is the difference between contexts and labels in Liquibase?
Contexts are defined by the changeset author, while labels allow deployment managers to control execution at runtime.

Q2: What changed in Liquibase 4.16.0?
The new contextFilter and label-filter settings make it clear when you are applying filter logic versus tagging.

Q3: Will older context or label settings still work?
Yes. The older context and --labels options are still supported for backward compatibility.

Q4: How do I specify a context filter in a changeset?
Use the contextFilter attribute in your changeset and run liquibase update --contexts=... to apply it at runtime.

Q5: Where can I learn more about contexts and labels?
Check the Liquibase documentation, release notes, or take the free “Managing Liquibase Changelogs” course at Liquibase University.

‍