• Reference
  • Version · 6.0
  • Change Automation Reference

ddl-lock-timeout

Last updated: August 14, 2026

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.

Default: None. If you do not set --ddl-lock-timeout, Liquibase does not change the session setting and the database default applies. In Oracle, the default value of DDL_LOCK_TIMEOUT is 0, which means NOWAIT. A DDL statement fails immediately with the ORA-00054 error instead of waiting for the lock.

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

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)

Unix:

JAVA_OPTS=-Dliquibase.ddlLockTimeout=<int>

Windows:

JAVA_OPTS=-D"liquibase.ddlLockTimeout"=<int>

Liquibase environment variable

LIQUIBASE_DDL_LOCK_TIMEOUT=<int>

PreviousdbmsNextdefault-catalog-name