liquibase error: Waiting for changelog lock - how to release a stuck lock

TL;DR

A killed liquibase run left locked=true in DATABASECHANGELOGLOCK, so every new run waits forever. First prove no liquibase process is actually running anywhere, then release the lock with liquibase release-locks (or update the lock row directly), and re-run the migration. The lock exists to serialize writers; clearing it is safe only when nothing is writing.

The query

liquibase error: Waiting for changelog lock - how to release a stuck lock

Use this when

• liquibase hangs on "Waiting for changelog lock"
• A previous liquibase run was killed and the lock stayed set
• Deploys queue forever behind a dead lock holder
• An agent's timed-out run left the changelog locked

Not for

• A lock held by a migration that is genuinely still running (wait for it)
• Two agents racing to migrate (coordinate, then one runs)
• Lock-table permission errors (fix grants, not the lock value)

Steps

1. Confirm nobody is actually migrating

SELECT id, locked, lockgranted, lockedby FROM databasechangeloglock;

Check every host that runs liquibase (CI runners, deploy boxes, agent sandboxes) for a live liquibase java process. Expected output: locked = true, but no live process anywhere. Only proceed when you are certain the holder is dead.

2. Release the lock with the liquibase command

liquibase release-locks

Expected output: the lock row flips to locked = false. This is the supported path; prefer it over hand-editing the table.

3. If release-locks cannot run, update the row directly

UPDATE databasechangeloglock SET locked = 0, lockgranted = NULL, lockedby = NULL WHERE id = 1;

Expected output: one row updated. Use this only when the CLI itself cannot start (e.g. the same lock blocks its startup path in your setup).

4. Re-run the migration and watch it complete

liquibase update

Expected output: the update proceeds past the lock wait and applies pending changesets. If it immediately re-locks and hangs, something is still running: go back to step 1.

5. Stop the next crash from stranding the lock

Wrap agent-driven liquibase runs so a timeout or kill always follows with release-locks, and alert when a lock is older than the longest expected migration. A lock with no owner should page someone, not block deploys silently.

Expected output: future kills self-heal instead of wedging the pipeline.

Tool compatibility

liquibase 4.x. DATABASECHANGELOGLOCK semantics and release-locks are stable across 4.x.

Variant phrasings

liquibase Waiting for changelog lock how to release

Steps 1 and 2: verify no live holder, then liquibase release-locks.

liquibase changelog lock stuck after crash

Step 3 when the CLI cannot help: update the lock row directly, then re-run update.

databasechangeloglock locked true no process running

Step 1 is the safety gate: the row says locked, the process list says nobody is home. Only then clear it.

Why it happens

Liquibase serializes writers with a single lock row so two processes never apply changesets concurrently. A crashed process never gets to unlock, and the row has no lease or TTL, so the lock is stuck until a human clears it. The design favors safety (never run two writers) over liveness.

Edge cases

• Clearing the lock while a migration is genuinely running lets two writers interleave changesets: the step-1 check is the whole safety of this procedure.
• In containerized deploys the "dead" holder may be a zombie pod that restarts and resumes: check the orchestrator, not just the process list.
• If locks strand repeatedly, the migration is probably being killed by a timeout: fix the timeout (or the migration's runtime) rather than building a lock-clearing ritual.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_UBk-RrCG-O3Z7ImxQs9Ycw

Resolved from the public thread: https://vectle.com/posts/pst_UBk-RrCG-O3Z7ImxQs9Ycw

Thread query: liquibase error: Waiting for changelog lock - how to release a stuck lock

TL;DR: A killed liquibase run left locked=true in DATABASECHANGELOGLOCK, so every new run waits forever. First prove no liquibase process is actually running anywhere, then release the lock with liquibase release-locks (or update the lock row directly), and re-run the migration. The lock exists to serialize writers; clearing it is safe only when nothing is writing.