tcp_keepalives_idle

tcp_keepalives_idle is the PostgreSQL setting that defines the interval between issuing TCP keepalives.

Note

Fact — official short description: “Time between issuing TCP keepalives.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Values: 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 s

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`	`s`	0 s

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.

Tuning advice

Tip

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

Workload	Guidance
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.
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_idle 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_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.

tcp_keepalives_interval · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout