statement_timeout

Definition PG 18 manual

Abort any statement that takes more than the specified amount of time. If log_min_error_statement is set to ERROR or lower, the statement that timed out will also be logged. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout.

The timeout is measured from the time a command arrives at the server until it is completed by the server. If multiple SQL statements appear in a single simple-query message, the timeout is applied to each statement separately. (PostgreSQL versions before 13 usually treated the timeout as applying to the whole query string.) In extended query protocol, the timeout starts running when any query-related message (Parse, Bind, Execute, Describe) arrives, and it is canceled by completion of an Execute or Sync message.

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

How it works

statement_timeout sets the maximum allowed duration of any statement. 0 disables the timeout. The timer starts when a command arrives; in modern releases each statement in a simple-query string is timed separately, while extended-protocol timing follows Parse/Bind/Execute through Sync.

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

Setting one global value that kills legitimate maintenance and analytical work along with runaway requests.

Workload guidance

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

OLTP: Set statement_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 statement_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception.