tcp_keepalives_interval

tcp_keepalives_interval is the PostgreSQL setting that defines the interval between TCP keepalive retransmits.

Note

Fact — official short description: “Time between TCP keepalive retransmits.”

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

Tuning advice

Tip

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

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

tcp_keepalives_idle · tcp_keepalives_count · tcp_user_timeout · client_connection_check_interval · authentication_timeout