tcp_keepalives_idle

Definition PG 18 manual

Specifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client. If this value is specified without units, it is taken as seconds. A value of 0 (the default) selects the operating system's default. On Windows, setting a value of 0 will set this parameter to 2 hours, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support TCP_KEEPIDLE or an equivalent socket option, and on Windows; on other systems, it must be zero. In sessions connected via a Unix-domain socket, this parameter is ignored and always reads as zero.

How it works

tcp_keepalives_idle defines the interval between issuing TCP keepalives. 0 means use the system default. It determines how long an otherwise idle TCP connection waits before the first keepalive probe; zero selects the operating-system default.

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

The effective failure window is derived from tcp_keepalives_idle, tcp_keepalives_interval, and tcp_keepalives_count, subject to operating-system support and any shorter network-device timeout.

Operational considerations

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

Tuning one keepalive component without calculating the full idle-plus-retransmit failure window.

Assuming PostgreSQL's requested value overrides unsupported platforms or a shorter firewall and load-balancer idle policy.

Choosing a value longer than the network device's idle timeout and never getting a useful probe first.

Workload guidance

OLAP: Long analytical connections need keepalive timing shorter than intervening network idle expiry but not so aggressive that transient loss aborts healthy jobs.

OLTP: Choose tcp_keepalives_idle with the other keepalive controls so total failure-detection time fits load-balancer, failover, and retry budgets. Confirm the operating system implements the requested socket option.

SMALL: Use operating-system defaults unless a measured network failure mode requires an override; tune the complete idle/interval/count tuple, not tcp_keepalives_idle alone.