idle_session_timeout

Definition PG 18 manual

Terminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout.

Unlike the case with an open transaction, an idle session without a transaction imposes no large costs on the server, so there is less need to enable this timeout than idle_in_transaction_session_timeout.

Be wary of enforcing this timeout on connections made through connection-pooling software or other middleware, as such a layer may not react well to unexpected connection closure. It may be helpful to enable this timeout only for interactive sessions, perhaps by applying it only to particular users.

How it works

idle_session_timeout sets the maximum allowed idle time between queries, when not in a transaction. 0 disables the timeout. It closes sessions idle outside a transaction; such sessions are usually cheap, and poolers may react badly to unexpected server-side closure.

idle_session_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 idle_session_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 idle_session_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 idle_session_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.

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