- Concept
- Version · 6.0
- Create
When should I use contexts, labels, or filter attributes?
Last updated: September 29, 2026
Contexts, labels, and the Liquibase Secure filter attributes are tools that help you control how Liquibase deploys changesets. Because they share many similarities and you can combine them on a changeset, it's sometimes difficult to decide which will help you achieve your goals. It becomes easier to make a choice when you think about it from the perspective of who needs to understand or control which changesets to execute, the changeset author or the deployment manager, and whether the runtime decision needs expression logic or a simple list.
What are the filterable attributes?
Contexts are added to changesets to control which changesets execute in a particular migration run. They describe/tag the changeset with the environment. The changeset author decides which environments the changeset should run in.
Labels group and classify changesets. They are frequently used when complex logic to select changesets is determined at runtime. The deployment manager decides which labeled changesets to run using a label-filter expression.
In Liquibase Secure 6.0 and later, four additional filterable attributes give you dimensions beyond environment and feature: teams, releases, keywords, and conditions. Each has a matching runtime argument, such as --teams-filter, that uses straight string matching with no logical operators.
Context use case example
In this scenario, contexts describe/tag the environment, and the changeset author decides which environments the changeset should run in.
A changeset author is creating test data for a particular version. The data is tagged with context="!prod AND v.1.1".
At runtime, Liquibase commands specify the environment and version with a context expression of --context-filter="test,v.1.1".
No runtime decision determines which changesets execute at runtime. Automation may be in place to always pass environment and artifact versions to the runtime context expression.
Label use case example
Labels describe/tag the changeset, and the deployment manager decides which labeled changesets to run.
The changeset author creates changesets for upcoming shopping cart features, but the decision about when these features will go to market has yet to be made.
The changeset author tags the changesets with labels="shopping-cart,feature-A".
Once the feature is ready to go live, a deployment engineer issues the Liquibase commands with a label expression of --label-filter="shopping-cart AND feature-A".
Filter attribute use case example
The teams, releases, keywords, and conditions attributes describe/tag additional dimensions of the changeset. Both the author and the deployment manager work with simple lists instead of expressions.
A changeset author tags each changeset with the owning team and target release: teams="security" releases="v2.1".
At deploy time, the deployment manager targets one team's changes for the release: liquibase update --teams-filter=security --releases-filter=v2.1.
The same tags can scope policy checks. For example, liquibase checks run --keywords-filter=pii inspects only the changesets tagged with that keyword.
How to choose
Attribute | Best for | Who decides at runtime | Filter matching |
Environments, such as | Changeset author (expression logic is set on the changeset) |
| |
Features, versions, and tickets that need complex runtime selection | Deployment manager |
| |
Team ownership | Either |
| |
Release trains | Either |
| |
A dimension you define, such as a business domain or compliance category | Either |
| |
Run circumstances, such as | Either |
|
You can combine multiple filter arguments in a single command. In every case, a changeset that does not have the attribute always runs, so filters narrow execution only among tagged changesets.
Note: The teams, releases, keywords, and conditions attributes require Liquibase Secure 6.0 or later.