set-contexts

Note: This is a Liquibase Pro command, so you need a Liquibase Pro License Key to use it.

The set-contexts command sets or replaces contexts on your changesets using your command line. This is an alternative to setting contexts directly in your changelog.

You can choose which changesets to target by specifying a changeset author, ID, path, or an existing context or label filter.

The command works with any SQL, XML, YAML, or JSON changelog. It also works with multiple changelogs specified with the include or includeAll tags. set-contexts is available in Liquibase 4.23.1+.

Uses

If you need to apply contexts to many changesets, manually inserting them into your changelog is slow and can lead to errors. Instead, use set-contexts to quickly add or replace contexts in bulk.

By default, Liquibase appends any contexts you specify with set-contexts to the list of contexts already on your changesets. However, if you set --force-replace to true, Liquibase drops existing contexts before adding the new ones.

The command is also useful if you want to standardize multiple similar contexts or replace deprecated ones. You can specify command arguments to control the formatting Liquibase uses when it inserts the contexts into your changelog.

After setting your contexts with set-contexts, you can deploy your changes with the update command. While deploying, specify the --context-filter command argument to control which changesets are run.

Syntax

To run the set-contexts command, specify the driver, classpath, and URL in Liquibase properties file. For more information, see Create and Configure a liquibase.properties File. You can also specify these properties in your command line.

Then run the set-contexts command:

liquibase set-contexts --changelog-file=example-changelog.xml --set-as=dev,test

For example, targeting changesets by author and existing label filter:

liquibase set-contexts
    --set-as="dev, stage"
    --changelog-file=release-02.sql
    --changeset-author="bob"
    --label-filter="rel-02"

Replacing existing contexts with --force-replace instead of appending them:

liquibase set-contexts
    --set-as=dev, stage
    --changelog-file=release-02.sql
    --changeset-author="bob"
    --context-filter="dev,uat,stage"
    --label-filter="rel-02"
    --force-replace=true

Note: Even though you're setting contexts with this command, you can still target changesets using both context-filter and label-filter.

Global arguments

Tip: For best results, specify all commands and parameters in the --kebab-case format in the CLI. If your preference is camelCase, it also works in the CLI.

Attribute Definition Requirements
--license-key

Your Liquibase Pro license key

 Required

Command arguments

Attribute Definition Requirements
--changelog-file

The root changelog

 Required
--set-as

Specifies the context(s)/label(s) to apply to the changesets you select. Case-insensitive. Separate multiple values with commas (equivalent to OR) or the AND operator. If you use a space between multiple values, you must surround the entire string with quotes. Otherwise, quotes are optional. For example, --set-as=dev, --set-as="(\!dev and test)" or qa, and --set-as="dev, test" are all valid. User-supplied regular expressions are not supported, but you can use * as a wildcard.

 Required
--changeset-author

The name of the author for the changeset. Supports * as a wildcard.

 Optional
--changeset-id

The changeset ID from the changelog.

 Optional
--changeset-path

The path to the changelog containing the changeset you want to roll back.

 Optional
--context-filter

Specifies the changeset contexts to match. Contexts are expressions you can add to changesets to control which changesets are executed in any particular migration run.

 Optional
--dbms

Specifies which database type a changeset is to be used for. See valid database type names on Liquibase Database Tutorials.

Optional
--default-catalog-name

Name of the default catalog to use for the database connection

 Optional
--default-schema-name

Name of the default schema to use for the database connection. If defaultSchemaName is set, then objects do not have to be fully qualified. This means you can refer to just mytable instead of myschema.mytable.

Tip: In Liquibase v4.23.0+, camelCase for defaultSchemaName works successfully. If you are on an earlier version, camelCase may not work as expected.

Note: The syntax liquibase.command.defaultSchemaName is valid for v4.19.0+. For prior versions, use defaultSchemaName.

 Optional
--driver

The JDBC driver class

 Optional
--driver-properties-file

The JDBC driver properties file

 Optional
--force-replace

If true, replace any existing contexts/labels with the new ones rather than appending them to the list. If you specify --force-replace without a value, Liquibase sets it to true. Default: false.

 Optional
--label-filter

Specifies the changeset labels to match. Labels are tags you can add to changesets to control which changeset will be executed in any migration run.

 Optional
--password

Password to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

 Optional
--url

The JDBC database connection URL. See Using JDBC URL in Liquibase.

 Optional
--username

Username to connect to the target database.

Tip: It is a best practice to store sensitive data in a Secrets Management tool with Liquibase Pro.

 Optional

Note: The username and password attributes are not required for connections and systems which use alternate means of authentication. Also, you can specify database credentials as part of the url attribute.

Output

When successful, the set-contexts command produces the following output:

* Changelog file 'changelog.xml' modified successfully.
Liquibase command 'set-contexts' was executed successfully.

If you specify an invalid value for the dbms argument:

Mismatched dbms for changeset 'createPrimaryTable::Liquibase Pro User::changelog.xml'

When there is an ignored changeset:

Ignoring changeset 'createSecondaryTable::Liquibase Pro User::changelog.xml'

When there is nothing to modify:

* Changelog file 'changelog.xml' was not modified.

Related links