Contexts
Contexts are expressions that control whether commands like update run certain changesets.You add contextFilters directly to changesets in your changelog and specify them at runtime using the --contexts
attribute in the CLI. Context names are case-insensitive strings.
By default, a database update runs all changesets in the changelog, regardless of what you specify in the CLI. If you add a contextFilter to a changeset, it only runs when you specify that context in the CLI, but unmarked changesets still run. If you do not specify any contexts in the CLI at runtime, every changeset in your changelog runs, even if they have contextFilters attached.
Here are examples of SQL, XML, JSON, and YAML changesets using the contextFilter attribute:

--changeset bob:1 contextFilter:test
insert into news (id, title) values (1, 'Liquibase 0.8 Released')

<changeSet id="2" author="bob" contextFilter="test">
<insert tableName="news">
<column name="id" value="1"/>
<column name="title" value="Liquibase 0.8 Released"/>
</insert>
</changeSet>

{
"changeSet": {
"id": "2",
"author": "bob",
"contextFilter": "test",
"changes": [
{
"insert": {
"tableName": "news",
"columns": [
{
"column": {
"name": "id",
"value": "1"
}
},
{
"column": {
"name": "title",
"value": "Liquibase 0.8 Released"
}
}
]
}
}
]
}
}

- changeSet:
id: 2
author: bob
contextFilter: test
changes:
- insert:
tableName: news
columns:
- column:
name: id
value: 1
- column:
name: title
value: "Liquibase 0.8 Released"
Context syntax
You can specify a context using AND
, OR
, !
, and parentheses in the changesets. Without parentheses, the order of operations is !
, AND
, and then OR
.
Examples:
contextFilter="!test"
contextFilter="v1.0 or map"
contextFilter="!qa and !master"
Using a ","
to separate contexts works like an OR
operation but with the highest precedence.
Examples:
- "test, qa" is the same as "test OR qa"
- "test, qa and master" is the same as "(test) OR (qa and master)"
Availability:
","
separator is available in all versions of Liquibase- "AND, OR, !, parentheses" are added in 3.2.0
- Prior to 4.13.0, the "contextFilter" attribute was called "context". A "context" attribute continues to act as an alias for "contextFilter"
Running contexts
You can only specify context filtering logic in a changeset definition, but you can still specify multiple contexts when running Liquibase in the CLI. However, you can only list out all the contexts that apply to the current Liquibase run.
liquibase --changelog-file=changelog.xml --contexts="test" update
If your changelog includes several changesets with complex and simple context filters such as contextFilter="qa and master and !dev"
for changeset 1 and contextFilter="test"
for changeset 2, you need to pass the following on the command line to deploy them:
liquibase --changelog-file=changelog.xml --contexts="test,qa,master" update
Using contexts for test data
If you manage your test data with Liquibase, it is best practice to have this data in line with all your other changesets, but marked with a "test"
contextFilter.
When you want your test data inserted, run a database update and specify the "test"
context in the CLI. When you need to migrate your production database,
don't include the "test"
context, and your test data will not be included.
Note: If you do not specify any contexts in the CLI at runtime, every changeset will
be applied, including those marked with a "test"
context.
If you have multiple test environments or test data sets, simply tag them with different contexts, like "min-test"
and "integration-test"
.
Using contexts to control test data is better than having a separate changelogs tree because later Change Types and changes will be applied to existing test data the same as they are applied to production data. If you had a set of test data that was created and simply added after the database is set up, you would be constantly manually updating your test data scripts to keep them in line with the current database schema.
Using contexts for multi-DBMS changelogs
You can use contexts to control which changesets are run on which databases, but there is an option to use the built in "dbms"
tag on the changeset tag.
Default context
You can specify a contextFilter attribute in the root DATABASECHANGELOG node to assign that context to all changesets in the changelog by default.
The specified contextFilter will have AND
with any contextFilters specified in changesets within the changelog file.
include
and includeAll
contexts
SYou can specify a contextFilter attribute in <include>
or <includeAll>
tags. If specified, the given contextFilter is added to all changesets in the included file(s).