Keep ALTER TABLE from blocking your app
An ALTER TABLE waits for an exclusive lock, and every reader that arrives behind it queues too, one migration stalls everyone. Setting lock_timeout makes the ALTER give up quickly instead of freezing the table.
Problem
What you're actually looking at
The symptom as it shows up on a real server.
ALTER TABLE needs an ACCESS EXCLUSIVE lock. If a long query already holds the table, the ALTER waits, and because its lock request is exclusive, every subsequent reader queues behind the ALTER. A single migration behind a slow query can freeze an entire table's traffic.
A Meridian schema_migration issues an ALTER on waybill_headers while a long_report still reads it. The ALTER waits, and an api_reader that arrives next is now stuck behind the ALTER, a two-level pile-up.
Simple terms
ALTER TABLE needs the strongest kind of lock on the table. If a slow query is already using that table, the ALTER has to wait, and here is the trap: because its lock request is exclusive, every new reader that arrives lines up behind the ALTER too. So one migration stuck behind one slow query can freeze all traffic to the table. Giving the ALTER a lock_timeout lets it give up quickly instead of taking everyone down with it.
Full runbook for this incident
- The full identify checklist, the exact signals that tell you it's this incident
- Every diagnostic query; lab output is attached only to the steps we actually captured
- The resolution path and the pitfalls that make it worse
- Mitigation steps to stop it recurring, plus a verify-you're-done query
Card required. Cancel before day 7 and you are not charged.
More in this category
Other Locking & concurrency runbooks
Neighbouring incidents that share the same diagnostic surface.
Connected
How this connects to the rest of the library
A live view of this page's real cross-references, what explains it, what fixes it, what to tune, and where to go next. Every link is an authored relationship, not a guess.
Fixes these errors
Need the full procedure?
Pro runbooks finish the incident path
Free runbooks teach the shape. Pro opens the full step transcript, edge cases, and prevention depth.