tcp_keepalives_count

Definition PG 18 manual

Specifies the number of TCP keepalive messages that can be lost before the server's connection to the client is considered dead. A value of 0 (the default) selects the operating system's default. This parameter is supported only on systems that support TCP_KEEPCNT or an equivalent socket option (which does not include 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_count sets the maximum number of TCP keepalive retransmits. Number of consecutive keepalive retransmits that can be lost before a connection is considered dead. 0 means use the system default. Together with idle and interval, it determines how many unanswered probes precede failure; zero selects the operating-system default where supported.

tcp_keepalives_count 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_count 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.

Assuming zero means no probes when it actually selects the operating-system default.

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