Skip to main content

How to Configure Timeouts

Sen Toren
Updated

Applies to

  • Liquibase Secure (Pro)
  • Liquibase Community (Open Source)

 

Summary

Use command-line parameters like --ddl-lock-timeout, --changelog-lock-wait-time-in-minutes, or --sqlplus-timeout to apply temporary timeouts for specific runs. Combine these with labels/contexts to isolate long-running operations. For JDBC-level tuning, leverage driver properties files.

 

Command-Line Timeout Parameters

You can directly specify timeout values on the command line for targeted runs. These parameters take precedence over properties files.

 

Oracle DDL Lock Timeout

Use --ddl-lock-timeout=<seconds> to set how many seconds Liquibase waits for the locks to become available before throwing the "resource busy" error message.

Example:

liquibase update --ddl-lock-timeout=18000

 

Changelog Lock Wait Time in Minutes

Use --changelog-lock-wait-time-in-minutes=<minutes> to set how many minutes Liquibase waits for a locked database to become available while another deployment completes.

If the DATABASECHANGELOGLOCK table is locked, you can use the liquibase release-locks command to release the lock on this table. Before you release the lock, you should ensure that there are no active Liquibase deployments in this database.

Example:

liquibase update --changelog-lock-wait-time-in-minutes=100

 

SQLPlus Timeout

Use --sqlplus-timeout=<seconds> to control the timeout for SQLPlus operations.

Example:

liquibase update --sqlplus-timeout=6000

 

Targeting Specific Changesets

While command-line parameters apply globally to a Liquibase run, you can combine them with labels or contexts to isolate long-running changesets. Example:

  1. Add a labels="long-running" attribute to problematic changesets:
<changeSet id="large_table_update" author="dev" labels="long-running">
      <!-- SQL operations --!>
</changeSet>

  2. Run only labeled changesets with an extended timeout:

liquibase update --labels=long-running --ddl-lock-timeout=18000

 

JDBC Driver-Level Timeouts

When using the JDBC driver for the database connection, use --driver-properties-file to pass JDBC-specific timeouts (e.g., oracle.jdbc.ReadTimeout). Example:

  1. Create a timeout.properties file with the following content:
oracle.jdbc.ReadTimeout=18000

  2. Reference the file in your command:

liquibase update --driver-properties-file=timeout.properties

Important Notes

  • Native Executors: The --ddl-lock-timeout works with the default JDBC executor but not SQLPlus. For SQLPlus, use --sqlplus-timeout.
  • No Per-Changeset Timeouts: As of Liquibase 4.33.0, there's no built-in method to set timeouts at the changeset level. A feature request is pending.
  • Property Override Hierarchy: Command-line parameters override liquibase.properties, so ensure your CLI arguments are correctly formatted.

 

Related Article(s)

Related to

Related articles

Comments

0 comments

Article is closed for comments.