tcp_keepalives_count

tcp_keepalives_count is the PostgreSQL setting that defines the maximum number of TCP keepalive retransmits.

Note

Fact — official short description: “Maximum number of TCP keepalive retransmits.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value0 – 2147483647: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueConnections and Authentication / TCP Settings: Upstream classification
Latest boot value , Value0: 0

Lifecycle

Fact	Value
First observed	PG9.0 (research boundary)
Present in	PG9.0–19 Beta 3
Removed in	No
Introduction commit	Not asserted: predates the PG9.0 research boundary
Commit date	—
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.0–19 Beta 3	`0`	—	0

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
OLAP	Long analytical connections need keepalive timing shorter than intervening network idle expiry but not so aggressive that transient loss aborts healthy jobs.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 unmodified; OLAP: PG9.0–19 Beta 3 unmodified; CRIT: PG9.0–19 Beta 3 unmodified; TINY: PG9.0–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

tcp_keepalives_idle · tcp_keepalives_interval · tcp_user_timeout · client_connection_check_interval · authentication_timeout