Contexts

Contexts in Liquibase are expressions you can add to changesets to control which will be executed in any particular migration run. Any string can be used for the context name and they are checked case-insensitively.

When you run the migrator though any of the available methods, you can pass in a set of contexts to run. Only changesets marked with the passed contexts will be run.

If you don't assign a context to a changeset, it will run all the time, regardless of what contexts you pass in to the migrator. If you do not specify a context when you run the migrator, all contexts will be run.

Here is an example of a changeset using the context attribute:

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

Context syntax

Contexts can be specified using AND, OR, !, and parentheses. Without parentheses the order of operations are !, AND, and then OR.

Examples:

  • contexts=''!test''
  • contexts=''v1.0 or map''
  • contexts=''!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

Running contexts

Though the context logic can only be specified in the changeset definition, you can still specify multiple contexts when running Liquibase. However, you can only list out all the contexts that apply to the current Liquibase run.

liquibase --changeLogFile=changelog.xml --contexts="test" update

If you have a changelog with a big amount of changesets that include complex and simple contexts such as contexts="test, dev, qa and master" and contexts="code", and you want to run only contexts="test, dev, qa and master", you need to pass the following on the command line:

liquibase --changeLogFile=changelog.xml --contexts="test,dev,qa,master" update

If you use contexts="test,dev,qa,master", Liquibase will only deploy changeset that include master in addition to any of the other three contexts. So, if you have a changeset with contexts=test, it will not be deployed when you specify --contexts=test,dev,qa,master because the changeset does not have contexts=test, master or contexts=test and master.

Using contexts for test data

If you manage your test data with Liquibase, the best way is to have this data in line with all your other changesets, but marked with a "test" context. That way, when you want your test data inserted, you can run the migrator with the "test" context. 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 context at all, 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 such as "min-test", "integration-test", and others.

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

Starting with Liquibase 3.5, you can specify a context attribute in the root DATABASECHANGELOG node to assign that context to all changesets in the changelog by default.

The specified context will have AND with any contexts specified in changesets within the changelog file.

include and includeAll contexts

Starting with Liquibase 3.5, you can specify a context attribute in <include> or <includeAll> tags. If specified, the given context is added to all changesets in the included file(s).