Liquibase–JDBC driver: graceful cancellation and timeout handling for changeSets

Expected behavior when a changeSet cancels or exceeds a time limit

When a Liquibase changeSet is cancelled or exceeds a time limit, the runtime behavior depends on the executor configuration and the transactional mode of the changeSet. Liquibase does not provide a native per-changeSet cancellation API; instead, timeout handling occurs at the JDBC statement level or through a global system property. If a changeSet runs with runInTransaction enabled (the default for most databases), any exception, including SQLTimeoutException, triggers a transactional rollback, leaving the database in the state prior to the changeSet's execution. However, if the changeSet declares runInTransaction=false, the failure is recorded as FAILED in the DATABASECHANGELOG, but any DDL or DML already transmitted to the database persists. This means non-idempotent changeSets can leave the database in a partially applied state, requiring manual rollback scripts or idempotent design. Additionally, JDBC-level timeouts via Statement.setQueryTimeout() can abort a statement after a configured duration, but the driver's SQLTimeoutException may not immediately cancel the underlying query; the database may continue processing until completion or until the connection is closed. Thread interruption in Liquibase's ChangeSetExecutor is not handled by default, so hanging threads may continue until the JVM process terminates or a custom ServiceListener aborts the connection.

Confirmed facts

1. Liquibase wraps changeSet execution in a JDBC Statement; runInTransaction=true provides automatic rollback on exception.
2. The --timeout flag sets liquibase.timeout, evaluated before changeSet execution, not as a per-statement timeout.
3. Statement.setQueryTimeout() enforces a per-statement timeout and throws SQLTimeoutException when exceeded.
4. Non-transactional changeSets record FAILED status but do not undo applied changes.

Steps to verify the behavior

1. Run Liquibase with -Dliquibase.timeout=5 and observe whether the changeSet logs FAILED after approximately 5 seconds, confirming the global timeout property behavior.
2. Execute a test changeSet with runInTransaction=false; after simulating a failure, query the DATABASECHANGELOG table to verify that applied changes remain, demonstrating the need for manual rollback in non-transactional mode.
3. Obtain a JDBC Connection from Liquibase's DataSource and call stmt.setQueryTimeout(30) on a statement; run a long-running query and confirm that SQLTimeoutException is thrown within 30 seconds.
4. Force-kill a Liquibase process mid-changeSet and inspect the DATABASECHANGELOG and database state; note whether the changeSet is marked FAILED and whether any DML persists, validating the transactional versus non-transactional boundary.

Open questions

Open questions remain:

• Should Liquibase expose a changeSet-level timeout attribute that maps to JDBC statement timeouts?
• How should a cancelled changeSet be recorded in the changelog—ran, failed, or a new state?
• What cleanup strategy is required for partially applied non-transactional changeSets?

Missing diagnostic detail: Does the changeSet use runInTransaction=true or false? This determines whether a transactional rollback can cleanly undo applied changes or whether manual intervention is required.