tcp_keepalives_interval

Definition PG 18 manual

Specifies the amount of time after which a TCP keepalive message that has not been acknowledged by the client should be retransmitted. 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 1 second, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support TCP_KEEPINTVL 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_interval defines the interval between TCP keepalive retransmits. 0 means use the system default. After probing begins, it spaces retransmissions and combines with tcp_keepalives_count to determine total failure-detection time.

tcp_keepalives_interval 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_interval 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.

Tuning the retransmit interval without considering tcp_keepalives_count and total failure-detection time.

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_interval 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_interval alone.