changelog-lock-wait-time-in-minutes parameter

The changelog-lock-wait-time-in-minutes global parameter is an integer value that sets the amount of time Liquibase waits for a locked database to become available. The default value is 5.

DATABASECHANGELOGLOCK table

The DATABASECHANGELOGLOCK table only allows a single instance of Liquibase to run at a time. This prevents conflicts between multiple developers working at the same time or multiple servers in a cluster that auto-run Liquibase on startup.

DATABASECHANGELOGLOCK has a column named LOCKED that is set to 1 while Liquibase is running and 0 otherwise. If you try to run Liquibase while the lock record is active, the following message is printed to STDOUT:

Waiting for changelog lock....

This message repeats until LOCKED is set to 0. If the amount of time specified in changelog-lock-wait-time-in-minutes passes and the lock is not released, Liquibase stops running.

Uses

Liquibase doesn’t automatically time out if a database update takes a long time to finish. If you need to run multiple database updates at once, and each of them takes a long time to complete, you can raise the value of changelog-lock-wait-time-in-minutes. This way, you don’t have to re-run commands that timed out.

If you need to limit system resources by halting processes in a "waiting" state, you can lower the value of changelog-lock-wait-time-in-minutes.

Setting the changelog-lock-wait-time-in-minutes parameter

You can set changelog-lock-wait-time-in-minutes 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 changelog-lock-wait-time-in-minutes as a Java system property from your command line:

java -Dliquibase.changelogLockWaitTimeInMinutes=<int>

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

JAVA_OPTS=-Dliquibase.changelogLockWaitTimeInMinutes=<int> && liquibase update --changelog-file=dbchangelog.xml

The syntax on Windows requires the set command:

set JAVA_OPTS=-Dliquibase.changelogLockWaitTimeInMinutes=<int> && liquibase update --changelog-file=dbchangelog.xml

liquibase.properties parameter

In Liquibase 4.1+, you can set changelog-lock-wait-time-in-minutes by adding the following to your liquibase.properties file:

liquibase.changelogLockWaitTimeInMinutes: <int>

CLI global parameter

You can use changelog-lock-wait-time-in-minutes as a global parameter in your command line with a single Liquibase command, such as update:

liquibase --changelog-lock-wait-time-in-minutes=<int> update --changelog-file=dbchangelog.xml

Environment variable (Liquibase Pro)

If you use Liquibase Pro, you can set changelog-lock-wait-time-in-minutes as an environment variable. The syntax on Mac/Linux is as follows:

LIQUIBASE_CHANGELOG_LOCK_WAIT_TIME_IN_MINUTES=<int>

The syntax on Windows requires the set command:

set LIQUIBASE_CHANGELOG_LOCK_WAIT_TIME_IN_MINUTES=<int>

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.

Related links