{"Entry":{"collection":"guc","key":"tcp_keepalives_idle","name":"tcp_keepalives_idle","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Connections and Authentication / TCP Settings","category_zh":"","changed_in":["14","16","18"],"changes":[{"documentation_changed":false,"fields":{},"from":"8.0","status":"added","to":"8.1"},{"documentation_changed":true,"fields":{},"from":"8.1","status":"changed","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.4","status":"changed","to":"9.0"},{"documentation_changed":true,"fields":{},"from":"9.1","status":"changed","to":"9.2"},{"documentation_changed":true,"fields":{},"from":"9.3","status":"changed","to":"9.4"},{"documentation_changed":true,"fields":{},"from":"9.6","status":"changed","to":"10"},{"documentation_changed":true,"fields":{},"from":"11","status":"changed","to":"12"},{"documentation_changed":false,"fields":{"category":{"from":"Client Connection Defaults / Other Defaults","to":"Connections and Authentication / Connection Settings"}},"from":"13","status":"changed","to":"14"},{"documentation_changed":true,"fields":{"category":{"from":"Connections and Authentication / Connection Settings","to":"Connections and Authentication / TCP Settings"}},"from":"15","status":"changed","to":"16"},{"documentation_changed":false,"fields":{"extra_desc":{"from":"A value of 0 uses the system default.","to":"0 means use the system default."}},"from":"17","status":"changed","to":"18"}],"content_hash":"0a385daebc9f643406c22ca9183697f94527857d9d3f7ebdcf429279b422f324","context":"","default_changed_in":[],"default_history":[{"from":"9.0","to":"19","value":"0 s"}],"editorial":{"advice":{"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_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.","small":"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."},"mechanism":["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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: tcp_keepalives_idle","url":"https://www.postgresql.org/docs/19/runtime-config-connection.html#GUC-TCP-KEEPALIVES-IDLE"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["tcp_keepalives_interval","tcp_keepalives_count","tcp_user_timeout","client_connection_check_interval","authentication_timeout"],"summary":"tcp_keepalives_idle is the PostgreSQL setting that defines the interval between issuing TCP keepalives."},"enumvals":[],"first_version":"8.1","group":"Connections and Authentication","group_slug":"connection","imported_at":"2026-09-27T17:57:32.139934+08:00","intro_commit":{},"key":"tcp_keepalives_idle","last_version":"20","max_val":"","min_val":"","name":"tcp_keepalives_idle","position":407,"present_in":["8.1","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"Specifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client.","short_desc_zh":"","source_rev":"english-manuals:96e2de3b09734674c3827a734a4547788a5cef8fc8c77c8709984abe3906f1f1","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"tcp_keepalives_idle","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"tcp_keepalives_idle","SourceRevision":"english-manuals:96e2de3b09734674c3827a734a4547788a5cef8fc8c77c8709984abe3906f1f1","Facts":{"boot_val":"0","category":"Connections and Authentication / TCP Settings","context":"user","description":"Specifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client. 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 2 hours, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support TCP_KEEPIDLE 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.","doc":{"anchor":"GUC-TCP-KEEPALIVES-IDLE","file":"runtime-config-connection.html","lang":"en","sha256":"567ba928f3e4c4783f548dc8a54f1e748f02bbe163924605f2132eb5b0da440d","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"0 means use the system default.","lang":"en","max_val":"2147483647","metadata_version":"18","min_val":"0","name":"tcp_keepalives_idle","short_desc":"Time between issuing TCP keepalives.","source":"pg-settings-source-snapshot","unit":"s","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-TCP-KEEPALIVES-IDLE","file":"runtime-config-connection.html","lang":"en","sha256":"567ba928f3e4c4783f548dc8a54f1e748f02bbe163924605f2132eb5b0da440d","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"tcp_keepalives_idle","SourceDatabase":"center","Version":"18","Locale":"en","Title":"tcp_keepalives_idle","Summary":"Specifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client. 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 2 hours, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support TCP_KEEPIDLE 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.","BodyHTML":"\u003cp\u003eSpecifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client. If this value is specified without units, it is taken as seconds. A value of 0 (the default) selects the operating system\u0026#39;s default. On Windows, setting a value of 0 will set this parameter to 2 hours, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support TCP_KEEPIDLE 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.\u003c/p\u003e","SourceRevision":"english-manuals:96e2de3b09734674c3827a734a4547788a5cef8fc8c77c8709984abe3906f1f1","ContentHash":"39e5be17b0aae20f9afdf6ae2c25dc871b48abb4990d093a862429611aef980f","Payload":{"description":"Specifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client. 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 2 hours, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support TCP_KEEPIDLE 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."}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["10","11","12","13","14","15","16","17","18","19","20","8.1","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}