should-run parameter

The should-run global parameter is a Boolean that determines whether Liquibase commands should run. By default, it is set to true.

Uses

If you use a Servlet Listener with Liquibase, you can set the should-run parameter to control whether specific servers run Liquibase commands. This can be useful if you do not want to set the LIQUIBASE_HOST_EXCLUDES or LIQUIBASE_HOST_INCLUDES attributes in your servlet listener, but still need to include or exclude some host names from running Liquibase.

If you are using the JEE CDI Integration for Liquibase, you can use should-run to stop Liquibase from performing updates when the CDI container boots.

If you are making test runs of an application, you can also use should-run to enable Liquibase commands on application startup but disable it on test runs.

Setting the should-run parameter

You can set should-run in four ways:

  • As a JVM system property
  • In your liquibase.properties file
  • As a global parameter in the CLI
  • As an environment variable (Liquibase Pro)

Java system property

You can set should-run as a Java system property from your command line:

java -Dliquibase.shouldRun=<true|false>

You can also set it with the JAVA_OPTS Environment Variable. The syntax on Mac/Linux is as follows:

JAVA_OPTS=-Dliquibase.shouldRun=<true|false> && liquibase update --changelog-file=dbchangelog.xml

The syntax on Windows requires the set command:

set JAVA_OPTS=-Dliquibase.shouldRun=<true|false> && liquibase update --changelog-file=dbchangelog.xml

liquibase.properties parameter

In Liquibase 4.1+, you can set should-run by adding the following to your liquibase.properties file:

liquibase.shouldRun: <true|false>

CLI global parameter

You can use should-run as a global parameter in your command line with a single Liquibase command, such as update:

liquibase --should-run=<true|false> update --changelog-file=dbchangelog.xml

Environment variable (Liquibase Pro)

If you use Liquibase Pro, you can set should-run as an environment variable. The syntax on Mac/Linux is as follows:

LIQUIBASE_SHOULD_RUN=<true|false>

The syntax on Windows requires the set command:

set LIQUIBASE_SHOULD_RUN=<true|false>

For more information, see Liquibase Environment Variables.

Note: The commands shown above only apply to the current shell. If you need to pass an environment variable to a child process without affecting the parent process, you can use the export command on Mac/Linux or the setx command on Windows.

Output

If you run Liquibase with should-run set to false, the output is:

Liquibase did not run because 'liquibase.shouldRun' was set to false