lock_timeout

Definition PG 18 manual

Abort any statement that waits longer than the specified amount of time while attempting to acquire a lock on a table, index, row, or other database object. The time limit applies separately to each lock acquisition attempt. The limit applies both to explicit locking requests (such as LOCK TABLE, or SELECT FOR UPDATE without NOWAIT) and to implicitly-acquired locks. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout.

Unlike statement_timeout, this timeout can only occur while waiting for locks. Note that if statement_timeout is nonzero, it is rather pointless to set lock_timeout to the same or larger value, since the statement timeout would always trigger first. If log_min_error_statement is set to ERROR or lower, the statement that timed out will be logged.

Setting lock_timeout in postgresql.conf is not recommended because it would affect all sessions.

How it works

lock_timeout sets the maximum allowed duration of any wait for a lock. 0 disables the timeout. The timer applies separately to each lock acquisition, not to total statement runtime; a statement_timeout at the same or lower value will fire first.

lock_timeout is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed.

Operational considerations

Changing lock_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.

Forgetting that zero usually disables the timeout or delegates behavior to the operating system.

Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.

Changing lock_timeout globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: Analytical work usually needs a larger or job-specific lock_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.

OLTP: Set lock_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.

SMALL: Use a conservative finite lock_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.