{"Entry":{"collection":"guc","key":"io_worker_idle_timeout","name":"io_worker_idle_timeout","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Resource Usage / I/O","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"18","status":"added","to":"19"}],"content_hash":"34f5603e9450050689e00f4c59b7d3dc7b59941aed12ad560bf05ffe335482f3","context":"","default_changed_in":[],"default_history":[{"from":"19","to":"19","value":"1 min"}],"editorial":{"advice":{"olap":"Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.","oltp":"Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.","small":"Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism."},"mechanism":["PostgreSQL describes io_worker_idle_timeout as follows: “Maximum time before idle I/O worker processes time out, for io_method=worker.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG19 Beta 3; boot_val is the compiled or initialized baseline, not proof of a running cluster's effective setting.","These controls govern the elastic background-worker pool used only when io_method is worker. io_min_workers keeps warm capacity, io_max_workers caps the pool, io_worker_launch_interval damps short bursts, and io_worker_idle_timeout lets unused workers retire; they do not raise a backend's separate io_max_concurrency ceiling.","Read it together with io_min_workers, io_max_workers, io_worker_launch_interval, io_method. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change."],"pitfalls":["Treating the measured boot_val for io_worker_idle_timeout as proof of the effective value on an initialized or managed cluster.","Applying a change as though it were immediate while pg_settings reports sighup context.","Changing this setting in isolation without checking the linked limits, observability, and rollback path.","Depending on beta behavior in production without retesting the PostgreSQL 19 final release."],"references":[{"title":"PostgreSQL 19 Beta 4: io_worker_idle_timeout","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-IO-WORKER-IDLE-TIMEOUT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["io_min_workers","io_max_workers","io_worker_launch_interval","io_method","io_max_concurrency","io_combine_limit"],"summary":"io_worker_idle_timeout — Maximum time before idle I/O worker processes time out, for io_method=worker. Observed in PG19 Beta 4; its last measured boot default is 1 min in PG19 Beta 4, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"19","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.413798+08:00","intro_commit":{"authored_at":"2026-04-08T19:06:14+12:00","discussion":["https://postgr.es/m/CA%2BhUKG%2Bm4xV0LMoH2c%3DoRAdEXuCnh%2BtGBTWa7uFeFMGgTLAw%2BQ%40mail.gmail.com"],"hash":"d1c01b79d4ae90e52bf9db9c05c9de17b7313e85","subject":"aio: Adjust I/O worker pool automatically.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=d1c01b79d4ae90e52bf9db9c05c9de17b7313e85"},"key":"io_worker_idle_timeout","last_version":"20","max_val":"","min_val":"","name":"io_worker_idle_timeout","position":187,"present_in":["19","20"],"short_desc":"Sets the time after which entirely idle I/O worker processes exit, reducing the size of pool to match demand.","short_desc_zh":"","source_rev":"english-manuals:84683b1f5dac73a95d1f496ddfae4f8bdc0724f1476dd87187e3d359b847406f","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"io_worker_idle_timeout","SourceDatabase":"center","Version":"20","SourceTable":"guc","SourceKey":"io_worker_idle_timeout","SourceRevision":"english-manuals:84683b1f5dac73a95d1f496ddfae4f8bdc0724f1476dd87187e3d359b847406f","Facts":{"boot_val":null,"category":"I/O","context":"","description":"Sets the time after which entirely idle I/O worker processes exit, reducing the size of pool to match demand. The default is 1 minute. This parameter can only be set in the postgresql.conf file or on the server command line. Only has an effect if io_method is set to worker.","doc":{"anchor":"GUC-IO-WORKER-IDLE-TIMEOUT","file":"runtime-config-resource.html","lang":"en","sha256":"ea0a5d7b8e66421d046db778b5fd97f6b61f6e0c6d784a5df79583500a5e1497","slug":"devel"},"documented":true,"enumvals":[],"extra_desc":"","lang":"en","max_val":null,"metadata_version":"","min_val":null,"name":"io_worker_idle_timeout","short_desc":"","source":"english-manual","unit":"","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-IO-WORKER-IDLE-TIMEOUT","file":"runtime-config-resource.html","lang":"en","sha256":"ea0a5d7b8e66421d046db778b5fd97f6b61f6e0c6d784a5df79583500a5e1497","slug":"devel"}},"MeasuredEvidence":{"metadata_version":""}},"Text":{"Collection":"guc","Key":"io_worker_idle_timeout","SourceDatabase":"pgweb","Version":"20","Locale":"zh-Hans","Title":"io_worker_idle_timeout","Summary":"","BodyHTML":"\u003cp\u003e设置完全空闲的 I/O 工作进程退出前经过的时间，从而将池大小缩减到与需求匹配。默认值为 1 分钟。此参数只能在\u003ccode\u003epostgresql.conf\u003c/code\u003e文件中或服务器命令行中设置。\u003c/p\u003e\u003cp\u003e仅当\u003ca href=\"/docs/devel/runtime-config-resource.html#GUC-IO-METHOD\" rel=\"nofollow\"\u003eio_method\u003c/a\u003e设置为\u003ccode\u003eworker\u003c/code\u003e时才有效。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"226240c96407d30ad982b2dc51b8000e3ea6715a420c1013e990a33100003527","Payload":{"carried_from":"19","carry_reason":"手册不含 pg_settings 事实，沿用 19","doc_html":"\u003cp\u003e设置完全空闲的 I/O 工作进程退出前经过的时间，从而将池大小缩减到与需求匹配。默认值为 1 分钟。此参数只能在\u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e文件中或服务器命令行中设置。\u003c/p\u003e\u003cp\u003e仅当\u003ca href=\"/docs/devel/runtime-config-resource.html#GUC-IO-METHOD\"\u003eio_method\u003c/a\u003e设置为\u003ccode class=\"literal\"\u003eworker\u003c/code\u003e时才有效。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}