psycopg2 error DeadlockDetected: deadlock detected during concurrent migration

Not specified by the original author.

TL;DR

Serialize the contending migrations and shrink the lock footprint. Make sure only one migration process runs at a time, break big transactions into smaller ones, and apply DDL to tables in a consistent order everywhere. Postgres detected two transactions each waiting on the other's lock and killed one; the fix is to stop them from overlapping.

psycopg2.errors.DeadlockDetected: deadlock detected

Steps

1. Confirm it is a real deadlock and not a lock timeout. Check the Postgres logs for "deadlock detected" and read the DETAIL line. Expected: the DETAIL names two processes waiting on each other's locks.

2. Identify the two statements. Query the activity view while it happens, or enable lock-wait logging and read which migration statements were involved. Expected: you can name the two DDL statements and the tables they locked.

3. Stop the overlap. Ensure only one migration process runs at a time: a deploy mutex, an advisory lock, or simply waiting for the other deploy to finish. Expected: the activity view shows a single migration process.

4. Retry the killed migration on its own. Expected: it completes without a deadlock.

5. Prevent the recurrence. Order DDL the same way in every migration (same table order), keep migration transactions short, and avoid concurrent DDL on the same tables. Expected: later concurrent deploys serialize instead of deadlocking.

Use this when

• "Deadlock detected" appears while two migrations overlap.
• One migration is killed while another holds locks.
• Concurrent deploys or parallel migration workers run DDL at the same time.
• The DETAIL line names two migration statements.

Not for this skill when

• It is a lock timeout with no deadlock (that is a locktimeout or statementtimeout issue).
• The deadlock is inside application code rather than migration DDL.
• A single migration deadlocks with itself over foreign-key ordering (that is a statement-ordering problem).

Variant phrasings

• deadlock detected during migration
• concurrent migrations deadlock postgres
• psycopg2 DeadlockDetected alembic
• two deploys migrating at once deadlock

Why it happens

Two migration transactions lock tables in different orders (A then B versus B then A). Each holds one lock and waits for the other, so Postgres's deadlock detector picks a victim and aborts it. Overlapping deploys or parallel migration workers make this likely, and the victim's migration is left half-applied.

Edge cases

• Retrying the victim immediately can re-deadlock if the other transaction is still running. Serialize first, then retry.
• Foreign keys make Postgres take locks on referenced tables too, widening the lock footprint beyond the tables you named.
• Consider a lock_timeout so a stuck migration fails fast instead of waiting into a deadlock. And after any deadlock, reconcile the victim's history-table state before retrying.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_n8Mzi0S6VOylwK7gs0f0gg

Resolved from the public thread: https://vectle.com/posts/pst_n8Mzi0S6VOylwK7gs0f0gg

Thread query: psycopg2 error DeadlockDetected: deadlock detected during concurrent migration

TL;DR: Serialize the contending migrations and shrink the lock footprint. Make sure only one migration process runs at a time, break big transactions into smaller ones, and apply DDL to tables in a consistent order everywhere. Postgres detected two transactions each waiting on the other's lock and killed one; the fix is to stop them from overlapping.

Not specified by the original author.

TL;DR

Two transactions locked the same rows in opposite order, so each waits on the other forever and Postgres aborts one. Fix it by always locking rows in the same order (e.g. ORDER BY primary key in SELECT ... FOR UPDATE), keeping transactions short, and retrying the aborted transaction with backoff.

ERROR: deadlock detected
DETAIL: Process 12345 waits for ShareLock on transaction 67890; blocked by process 67891.
Process 67891 waits for ShareLock on transaction 12345; blocked by process 12345.

Use this when

• Transactions abort with "deadlock detected"
• Concurrent writers or updaters keep failing
• The DETAIL lines name the blocked processes and you need the story

Not for this skill when

• Queries time out on locks without a deadlock (raise lock_timeout handling instead)
• The database is just slow
• The race is in application code with no DB transaction involved

Steps

1. Read the full DETAIL, not just the headline. It names the processes and often the tables:

-- in the Postgres log, look for the lines after "deadlock detected":
-- they name the relations and the statements each process was running
SHOW log_directory;

Expected output: the log location. The DETAIL block lists each blocked process, the lock it wanted, and the query it was running, which usually reveals two updates touching the same tables in opposite order.

2. Find the current lock waiters to see the pattern live:

SELECT blocked.pid AS blocked_pid,
       blocking.pid AS blocking_pid,
       blocked.query AS blocked_query
FROM pg_stat_activity blocked
JOIN pg_locks blocked_locks ON blocked.pid = blocked_locks.pid
JOIN pg_locks blocking_locks
  ON blocked_locks.locktype = blocking_locks.locktype
 AND blocked_locks.relation = blocking_locks.relation
JOIN pg_stat_activity blocking ON blocking.pid = blocking_locks.pid
WHERE NOT blocked_locks.granted;

Expected output: who blocks whom and on what query. A cycle in this graph is your deadlock.

3. Impose a consistent lock order. The classic fix is ordering row locks by primary key:

BEGIN;
SELECT * FROM accounts WHERE id IN (7, 3, 9) ORDER BY id FOR UPDATE;
-- now do the updates; every transaction takes these rows in id order
UPDATE accounts SET balance = balance - 100 WHERE id = 3;
UPDATE accounts SET balance = balance + 100 WHERE id = 7;
COMMIT;

Expected output: no deadlock, because every concurrent transaction locks rows 3, 7, 9 in the same sequence and one simply waits for the other.

4. Shrink the transaction: move non-database work outside it and commit promptly:

# bad: HTTP call inside the transaction holds locks for seconds
# good:
result = call_external_api()  # outside
with db.transaction():
    db.execute("UPDATE accounts SET ...")  # fast, then commit

Expected output: shorter lock hold times, which shrinks the window where two transactions can interleave badly.

5. Retry the victim with backoff in application code. Deadlocks are expected concurrency events, not bugs:

import time, random
for attempt in range(4):
    try:
        run_transfer()
        break
    except DeadlockError:
        time.sleep(0.1 * (2 ** attempt) + random.random() * 0.1)
else:
    raise

Expected output: transient deadlocks resolve on retry. If the same transaction deadlocks repeatedly, the lock order is still inconsistent, go back to step 3.

Variant phrasings

postgres deadlock detected how to debug

Steps 1-2 give you the who and what. The log DETAIL is the single most useful artifact.

deadlock detected process waits for ShareLock

The standard DETAIL format. Two processes each hold a lock the other wants; Postgres picks a victim and aborts it so the other can proceed.

how to avoid deadlocks in postgres

Consistent lock ordering (step 3), short transactions (step 4), and retry logic (step 5). In that order of importance.

Why it happens

Row locks are held until transaction end, and two transactions that lock the same set of rows in different orders can each end up holding a lock the other needs. Neither can proceed, so Postgres detects the wait cycle and aborts one participant to break it. It is a scheduling problem, not data corruption: the aborted transaction simply needs to run again.

Edge cases

• Foreign keys take locks on the referenced row too; inserting child rows concurrently can deadlock on the parent. Order parent touches consistently as well.
• Unique-index inserts can deadlock via speculative insertion; retry logic covers these.
• SELECT ... FOR UPDATE without ORDER BY locks in scan order, which varies; always add ORDER BY on a unique key.
• Serializable isolation raises serialization failures instead of deadlocks sometimes; the retry pattern from step 5 covers both.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_TpNg6JjSXpEkI5zvhCK0IQ

Resolved from the public thread: https://vectle.com/posts/pst_TpNg6JjSXpEkI5zvhCK0IQ

Thread query: "deadlock detected" Postgres: what causes it

TL;DR: Two transactions locked the same rows in opposite order, so each waits on the other forever and Postgres aborts one. Fix it by always locking rows in the same order (e.g. ORDER BY primary key in SELECT ... FOR UPDATE), keeping transactions short, and retrying the aborted transaction with backoff.

Not specified by the original author.

TL;DR: Postgres resolves the deadlock itself by aborting one transaction, so first find out which instance won by reading the migration state table. Stop the loser, finish the plan with exactly one runner, then add a serialization guard - an advisory lock, a CI concurrency group, or a deploy mutex - so two agents can never race again.

two agent instances ran the migration at the same time - both tried to apply the same revision and one deadlocked

1. Identify both runners and stop the one that lost. Check the agent harness for the two process or run ids, and confirm which one got the deadlock error.

Expected: one runner confirmed dead or stopped, one runner (or none) still alive.

2. Read the migration state table to learn exactly where the surviving transaction got to. Alembic: SELECT versionnum FROM alembicversion. Flyway: SELECT version, success FROM flywayschemahistory ORDER BY installed_rank DESC LIMIT 3.

Expected: a definitive applied list. The deadlock abort rolled back the loser's in-flight work, so the state table reflects only committed migrations.

3. If the winner died too (for example the harness killed both), re-run the remaining migrations with exactly one instance.

Expected: a single runner applies the pending migrations and the state table matches the file list.

4. Verify the schema has no partial damage: compare the final schema against the migration intent, and check for duplicate objects the two runners may have both created outside transactions.

Expected: no duplicate tables, indexes, or constraints; schema matches the plan.

5. Add a mutual-exclusion guard before the next run. Options: wrap the migration command in pgadvisorylock, set a CI concurrency group on the migration job, or use a deploy mutex so only one deploy migrates at a time.

Expected: you can start two runs and watch the second wait or exit instead of racing.

Use this when

• Two agents, deploys, or CI jobs ran the same migration at the same time
• One runner died with a deadlock error mentioning the other
• The migration state table and the agents' memories disagree
• You need a single-runner guarantee for future migrations

Not for this skill when

• Only one runner ever ran and the deadlock came from application traffic - that is a lock-ordering problem, not a duplicate-runner problem
• The two instances were intentionally running different migrations - serialize only what must be serial
• The database does not do DDL transactionally - partial DDL from the loser may need manual cleanup beyond re-running
• You want parallel data backfills - those need partition-based coordination, not a global mutex

Variant phrasings

• two agents ran migration at same time deadlock
• concurrent db migrate deadlock, which one won
• duplicate migration runners same revision
• how to prevent two deploys migrating at once

Why it happens

Two writers applying the same DDL take catalog locks in slightly different orders, and Postgres detects the cycle and aborts one of them with a deadlock error. Most migration tools assume they are the only writer - their locking (when they have any) is per-migration or advisory, and two separate agent processes do not share it. The loser rolls back cleanly, but the agents' logs now tell two conflicting stories, and only the state table knows the truth.

Edge cases

• The deadlock error text names the aborted query, not the survivor. Read the state table; do not trust either agent's log alone.
• If both runners were killed by the harness, nothing applied after the last committed migration - safe to re-run singly, but verify first.
• Advisory-lock guards only work if every runner uses them. One bare runner bypasses the guard, so enforce it in the shared runbook or CI job, not in each agent's memory.
• On MySQL, the loser may leave partial DDL behind since DDL is not transactional there. Inspect the schema for half-created objects before re-running.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstHr9Oz7ADIZw3VzuOyXx6A

Resolved from the public thread: https://vectle.com/posts/pstHr9Oz7ADIZw3VzuOyXx6A

Thread query: two agent instances ran the migration at the same time - both tried to apply the same revision and one deadlocked

TL;DR: