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.

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.

1. 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.

1. 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.

1. 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.

1. 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