lock_timeout
Aborts any statement that waits longer than this many milliseconds while trying to acquire a lock. A value of zero, the default, disables the timeout entirely, the statement then waits as long as it takes.
Defaults and ranges on this page were read from pg_settings on live PostgreSQL 18.4.
What this means
By default a statement waits forever for the lock it needs: if something else is holding that row or table, your query just sits there. lock_timeout puts a ceiling on the wait, after this many milliseconds without getting the lock, the statement gives up and errors out instead of blocking your connection. Zero, the default, means no ceiling. You set it for one session or one transaction (never globally) when a short, bounded wait that fails cleanly beats hanging indefinitely.
When it matters
Set per-session or per-transaction (never in postgresql.conf, which would affect every session) whenever a statement should give up on a lock after a short, bounded wait instead of blocking indefinitely or failing instantly.
| Default | 0 ms |
|---|---|
| Range | 0 – 2147483647 |
| Category | Locking |
SHOW lock_timeout;Tradeoffs
- • Too low (a few ms): ordinary, brief lock waits that would have succeeded start failing with SQLSTATE 55P03 for no real reason.
- • Too high: it stops being meaningfully different from leaving it disabled, the app still ends up waiting a long time before giving up.
- • The could-not-obtain-lock-on-row (55P03) lab on this platform measured lock_timeout = 500ms causing a real ~501.8ms wait before cancellation, proof the GUC's wait window is honored almost exactly, not just approximately.
Workload profiles
General OLTP
Leave at the default (0, disabled) unless a specific statement needs a bounded wait.
Most row-lock contention resolves in milliseconds; a global timeout is rarely the right tool.
Queue-like or worker tables
Set a short lock_timeout (e.g. 250-1000ms) per session around the specific locking statement, or use NOWAIT/SKIP LOCKED instead if any wait at all is unacceptable.
Tested in the could-not-obtain-lock-on-row (55P03) lab: NOWAIT fails instantly with zero wait, while lock_timeout fails only after the configured wait elapses, pick based on whether the app can tolerate a short wait.