{"Entry":{"collection":"guc","key":"idle_session_timeout","name":"idle_session_timeout","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Client Connection Defaults / Statement Behavior","category_zh":"","changed_in":["18"],"changes":[{"documentation_changed":false,"fields":{},"from":"13","status":"added","to":"14"},{"documentation_changed":false,"fields":{"extra_desc":{"from":"A value of 0 turns off the timeout.","to":"0 disables the timeout."}},"from":"17","status":"changed","to":"18"}],"content_hash":"42644475eb551920d065f162f86709bdc6960745edd82f00e4c86f4422802798","context":"","default_changed_in":[],"default_history":[{"from":"14","to":"19","value":"0 ms"}],"derived_content_hash":"d64414c4f17df0956c071f93a70d193d63580ac549e8d09565f12c7da31b6f81","editorial":{"advice":{"olap":"Analytical work usually needs a larger or job-specific idle_session_timeout; preserve a finite guardrail for abandoned work without killing legitimate long scans.","oltp":"Set idle_session_timeout from the service latency and failure budget, preferably per role or application. Test retries and cancellation paths before enforcing a cluster-wide value.","small":"Use a conservative finite idle_session_timeout only when the client or operating system handles termination correctly; verify that maintenance still has a dedicated exception."},"mechanism":["idle_session_timeout sets the maximum allowed idle time between queries, when not in a transaction. 0 disables the timeout. It closes sessions idle outside a transaction; such sessions are usually cheap, and poolers may react badly to unexpected server-side closure.","idle_session_timeout 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.","Timeouts overlap: the first applicable deadline wins, while client, pooler, TCP, and server cancellation behavior determines whether work is retried, canceled, or the session is closed."],"pitfalls":["Changing idle_session_timeout in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.","Forgetting that zero usually disables the timeout or delegates behavior to the operating system.","Setting overlapping deadlines without deciding which layer owns retries, cancellation, and connection disposal.","Changing idle_session_timeout globally without a rollback plan and a client or operational compatibility test."],"references":[{"title":"PostgreSQL 19 Beta 4: idle_session_timeout","url":"https://www.postgresql.org/docs/19/runtime-config-client.html#GUC-IDLE-SESSION-TIMEOUT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["statement_timeout","lock_timeout","transaction_timeout","idle_in_transaction_session_timeout","deadlock_timeout"],"summary":"idle_session_timeout is the PostgreSQL setting that defines the maximum allowed idle time between queries, when not in a transaction."},"enumvals":[],"first_version":"14","group":"Client Connection Defaults","group_slug":"client","imported_at":"2026-09-27T17:57:31.383209+08:00","intro_commit":{"authored_at":"2021-01-06T18:28:42-05:00","discussion":["https://postgr.es/m/763A0689-F189-459E-946F-F0EC4458980B@hotmail.com"],"hash":"9877374bef76ef03923f6aa8b955f2dbcbe6c2c7","subject":"Add idle_session_timeout.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=9877374bef76ef03923f6aa8b955f2dbcbe6c2c7"},"key":"idle_session_timeout","last_version":"20","max_val":"","min_val":"","name":"idle_session_timeout","position":175,"present_in":["14","15","16","17","18","19","20"],"repair_provenance":{"original_source_revision":"english-manuals:0e75ad2eb947e27c01822d6241ac5e860a3638d57b14b9ec974a22f372be9a20","receipt_sha256":"9eb950199df4afecb13c6ed2a9a98c5839d38c91d494b50f07f3b7130c372d19","repair":"wiki-repair-20261023"},"short_desc":"Terminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time.","short_desc_zh":"","source_rev":"wiki-repair-20261023:793b8aeec6be70198aeb337977ba79c9a26747321f2bb54dc0c23b623147fd0f","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"idle_session_timeout","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"idle_session_timeout","SourceRevision":"wiki-repair-20261023:793b8aeec6be70198aeb337977ba79c9a26747321f2bb54dc0c23b623147fd0f","Facts":{"boot_val":"0","category":"Client Connection Defaults / Statement Behavior","context":"user","description":"Terminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout. Unlike the case with an open transaction, an idle session without a transaction imposes no large costs on the server, so there is less need to enable this timeout than idle_in_transaction_session_timeout. Be wary of enforcing this timeout on connections made through connection-pooling software or other middleware, as such a layer may not react well to unexpected connection closure. It may be helpful to enable this timeout only for interactive sessions, perhaps by applying it only to particular users.","description_zh":"终止不在打开的事务中、且空闲（即等待客户端查询）超过指定时长的任何会话。如果指定值时不带单位，则以毫秒为单位。零值（默认值）禁用此超时。 不像打开事务的情况，没有事务的空闲会话不会给服务器带来很大的开销，因此启用此超时的需要比 idle_in_transaction_session_timeout 更少。 应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时，因为这样的层可能不会很好地响应意外的连接关闭。只对交互会话启用此超时可能有所帮助，也许只对特定用户应用它。","description_zh_html":"\u003cp\u003e\n        终止不在打开的事务中、且空闲（即等待客户端查询）超过指定时长的任何会话。如果指定值时不带单位，则以毫秒为单位。零值（默认值）禁用此超时。\n       \u003c/p\u003e\u003cp\u003e\n        不像打开事务的情况，没有事务的空闲会话不会给服务器带来很大的开销，因此启用此超时的需要比 \u003ccode class=\"varname\"\u003eidle_in_transaction_session_timeout\u003c/code\u003e 更少。\n       \u003c/p\u003e\u003cp\u003e\n        应谨慎对通过连接池软件或其他中间件建立的连接强制执行此超时，因为这样的层可能不会很好地响应意外的连接关闭。只对交互会话启用此超时可能有所帮助，也许只对特定用户应用它。\n       \u003c/p\u003e","doc":{"anchor":"GUC-IDLE-SESSION-TIMEOUT","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"0 disables the timeout.","lang":"en","max_val":"2147483647","metadata_version":"18","min_val":"0","name":"idle_session_timeout","short_desc":"Sets the maximum allowed idle time between queries, when not in a transaction.","source":"pg-settings-source-snapshot","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-client.html","sha256":"1882f8fd5576909c4fcc44af53077378871e05f5be67723f20fe300273024767"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":"ms","vartype":"integer","zh_from":"same-version-pgdoc"},"ManualEvidence":{"doc":{"anchor":"GUC-IDLE-SESSION-TIMEOUT","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"idle_session_timeout","SourceDatabase":"center","Version":"18","Locale":"en","Title":"idle_session_timeout","Summary":"Terminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout. Unlike the case with an open transaction, an idle session without a transaction imposes no large costs on the server, so there is less need to enable this timeout than idle_in_transaction_session_timeout. Be wary of enforcing this timeout on connections made through connection-pooling software or other middleware, as such a layer may not react well to unexpected connection closure. It may be helpful to enable this timeout only for interactive sessions, perhaps by applying it only to particular users.","BodyHTML":"\u003cp\u003eTerminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout. Unlike the case with an open transaction, an idle session without a transaction imposes no large costs on the server, so there is less need to enable this timeout than idle_in_transaction_session_timeout. Be wary of enforcing this timeout on connections made through connection-pooling software or other middleware, as such a layer may not react well to unexpected connection closure. It may be helpful to enable this timeout only for interactive sessions, perhaps by applying it only to particular users.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:793b8aeec6be70198aeb337977ba79c9a26747321f2bb54dc0c23b623147fd0f","ContentHash":"f4fa829996237a032e3567647230df1ae5151a8e37634fb3e3adaa9e7e53e196","Payload":{"description":"Terminate any session that has been idle (that is, waiting for a client query), but not within an open transaction, for longer than the specified amount of time. If this value is specified without units, it is taken as milliseconds. A value of zero (the default) disables the timeout. Unlike the case with an open transaction, an idle session without a transaction imposes no large costs on the server, so there is less need to enable this timeout than idle_in_transaction_session_timeout. Be wary of enforcing this timeout on connections made through connection-pooling software or other middleware, as such a layer may not react well to unexpected connection closure. It may be helpful to enable this timeout only for interactive sessions, perhaps by applying it only to particular users."}},"RequestedLocale":"en","Fallback":false,"Versions":["14","15","16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}