ddl-lock-timeout

The --ddl-lock-timeout global parameter is an integer value available in Liquibase 4.6.2 and later. It lets you specify the number of seconds a DDL command should wait for the locks to become available before throwing the "resource busy" error message. This applies only to Oracle databases.

Note: The --ddl-lock-timeout parameter works with the default JDBC Liquibase executor. It does not require the SQL Plus native executor.

Uses

DDL (Data Definition Language) commands are a subset of SQL commands. DDL commands like CREATE and DROP define the database schema, such as creating and modifying structures in the database, but not data in those structures.

When you use a DDL command in a database like Oracle, the database tries to acquire "locks" on the resource(s) you're accessing. This ensures that your command doesn't interfere with separate operations, and vice versa.

When you run a Liquibase command like update containing a changeset with a DDL operation (such as the createTable Change Type), Liquibase asks Oracle to acquire a lock on the resource you specified in your changeset.

The --ddl-lock-timeout parameter lets you control how long Liquibase waits for Oracle to release the resource lock:

  • If you want Oracle to wait a longer time, set a higher value for --ddl-lock-timeout. This may be useful if many concurrent processes are competing to access the same resources in your database.
  • If you want Oracle to wait a shorter time, set a lower value for --ddl-lock-timeout. This may be useful if you have a rapid-response system and prefer slow DDL operations to fail rather than hang for a long time.

If Liquibase cannot acquire the lock within the specified timeout period, the Liquibase operation fails and Oracle throws a "resource busy" error:

ERROR at line 1: ORA-00054: resource busy and acquire with NOWAIT specified or timeout expired

Syntax

You can set this parameter in the following ways:

Option Syntax
Liquibase properties file (defaults file) 
liquibase.ddlLockTimeout: <int>
Global flow file argument (example) 
stages:
  Default:
    actions:
      - type: liquibase
        command: update
        globalArgs: { ddl-lock-timeout: "<int>" }
Global CLI parameter 
liquibase
 --ddl-lock-timeout=<int> update
 --changelog-file=example-changelog.xml

JVM system property (JAVA_OPTS Environment Variable)

 
JAVA_OPTS=-Dliquibase.ddlLockTimeout=<int>
Liquibase Environment Variables 
LIQUIBASE_DDL_LOCK_TIMEOUT=<int>

For more information, see Working with Command Parameters.

Related links