changelog-lock-poll-rate parameter

The changelog-lock-poll-rate global parameter is an integer that sets the number of seconds Liquibase waits to check if a changelog lock has been released. The default value is 10.

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. The number of seconds Liquibase waits before checking the lock status at each interval is determined by the value of changelog-lock-poll-rate.

Uses

If you need to run multiple database updates at once and want to minimize the amount of unused time between deployments, you can lower the value of changelog-lock-poll-rate. This way, Liquibase will check more frequently whether the changelog lock has been released.

If you need to limit system resources, or if you know that the changelog lock will be active for a long time, you can raise the value of changelog-lock-poll-rate.

Setting the changelog-lock-poll-rate parameter

You can set changelog-lock-poll-rate 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-poll-rate as a Java system property by using the JAVA_OPTS Environment Variable in your command line. The syntax on Mac/Linux is as follows:

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

The syntax on Windows requires the set command:

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

liquibase.properties parameter

In Liquibase 4.1+, you can set changelog-lock-poll-rate by adding the following to your liquibase.properties file:

liquibase.changeLogLockPollRate: <int>

CLI global parameter

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

liquibase --changelog-lock-poll-rate=<int> update --changelog-file=dbchangelog.xml

Environment variable (Liquibase Pro)

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

LIQUIBASE_CHANGELOG_LOCK_POLL_RATE=<int>

The syntax on Windows requires the set command:

set LIQUIBASE_CHANGELOG_LOCK_POLL_RATE=<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