{"Entry":{"collection":"guc","key":"io_workers","name":"io_workers","aliases":[],"metadata":{"baseline":false,"boot_human":"3","boot_val":"3","category":"Resource Usage / I/O","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"17","status":"added","to":"18"},{"documentation_changed":false,"fields":{},"from":"18","status":"removed","to":"19"}],"content_hash":"6ddb28feaf2c9b5dc6194696bff642da5338e33ea528cf6d5fa489f2e06c9cf3","context":"sighup","default_changed_in":[],"default_history":[{"from":"18","to":"18","value":"3"}],"derived_content_hash":"1ab0a97073bc529fdb4eb46a29b06f21293ab97b357f768790f4e67dfe4d970b","editorial":{"advice":{"olap":"Sustained eligible scans can benefit from enough I/O workers to feed storage, but extra processes add scheduling overhead and cannot exceed the per-process or device concurrency bottleneck. Compare throughput and worker utilization; request size is controlled elsewhere.","oltp":"Tune io_workers only when io_method=worker. Start from the PG18 default 3, measure worker saturation, CPU use, and tail latency, and increase the pool only when queued eligible I/O waits for worker execution rather than for the device.","small":"Keep 3 or a measured smaller value when process and CPU budgets are tight. io_workers has no effect under io_uring or sync, so never spend tuning effort on it until io_method is confirmed as worker."},"mechanism":["io_workers sets the number of dedicated I/O worker processes used by PostgreSQL 18 when io_method=worker. It has no effect for io_uring or sync.","I/O workers execute asynchronous requests on behalf of database processes; this is an execution pool, distinct from parallel query workers and background worker slots.","Changing the count is reloadable, but useful capacity still depends on io_max_concurrency, workload queue depth, storage latency, and CPU. More workers do not guarantee more device throughput. Its SIGHUP context allows configuration reload without a server restart."],"pitfalls":["Changing io_workers while io_method is io_uring or sync, where it has no effect.","Treating worker-process count as bytes per request or as the per-process I/O ceiling.","Adding workers when the storage device, not the worker pool, is already saturated.","Forgetting that the reloadable pool still consumes process slots, CPU, and scheduling capacity."],"references":[{"title":"PostgreSQL 18: io_workers","url":"https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-WORKERS"}],"related":["io_method","io_max_concurrency","effective_io_concurrency","maintenance_io_concurrency","max_worker_processes"],"summary":"io_workers — Number of IO worker processes, for io_method=worker. Observed in PG18; its last measured boot default is 3 in PG18, with sighup context. It was removed in PG19 Beta 4."},"enumvals":[],"first_version":"18","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.417966+08:00","intro_commit":{"authored_at":"2025-03-18T10:52:33-04:00","discussion":["https://postgr.es/m/uvrtrknj4kdytuboidbhwclo4gxhswwcpgadptsjvjqcluzmah%40brqs62irg4dt","https://postgr.es/m/20210223100344.llw5an2aklengrmn@alap3.anarazel.de","https://postgr.es/m/stj36ea6yyhoxtqkhpieia2z4krnam7qyetc57rfezgk4zgapf@gcnactj4z56m"],"hash":"55b454d0e14084c841a034073abbf1a0ea937a45","subject":"aio: Infrastructure for io_method=worker","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=55b454d0e14084c841a034073abbf1a0ea937a45"},"key":"io_workers","last_version":"18","max_val":"32","min_val":"1","name":"io_workers","position":189,"present_in":["18"],"repair_provenance":{"original_source_revision":"english-manuals:ccd93e03547fcf037147970cb0bed786cd5d118345b5eb08d0ab5e0d86da3f92","receipt_sha256":"aabe9b91f859bc676ebb249dab9abe601ee107905a331a410337616bde8eaa2b","repair":"wiki-repair-20261023"},"short_desc":"Selects the number of I/O worker processes to use.","short_desc_zh":"","source_rev":"wiki-repair-20261023:7e1d489032134803ceaec180038f00fa35362b11be481654acec97833aefb2c3","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"io_workers","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"io_workers","SourceRevision":"wiki-repair-20261023:7e1d489032134803ceaec180038f00fa35362b11be481654acec97833aefb2c3","Facts":{"boot_val":"3","category":"Resource Usage / I/O","context":"sighup","description":"Selects the number of I/O worker processes to use. The default is 3. 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.","description_zh":"选择要使用的 I/O 工作进程数量。默认值为 3。此参数只能在 postgresql.conf 文件中或服务器命令行中设置。 仅当 io_method 设置为 worker 时才有效。","description_zh_html":"\u003cp\u003e\n         选择要使用的 I/O 工作进程数量。默认值为 3。此参数只能在\n         \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e 文件中或服务器命令行中设置。\n        \u003c/p\u003e\u003cp\u003e\n         仅当 \u003ca class=\"xref\" href=\"/zh/docs/18/runtime-config-resource.html#GUC-IO-METHOD\"\u003eio_method\u003c/a\u003e 设置为 \u003ccode class=\"literal\"\u003eworker\u003c/code\u003e 时才有效。\n        \u003c/p\u003e","doc":{"anchor":"GUC-IO-WORKERS","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"32","metadata_version":"18","min_val":"1","name":"io_workers","short_desc":"Number of IO worker processes, for io_method=worker.","source":"pg-settings-source-snapshot","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-resource.html","sha256":"f5fedbf88ec5f973aaf4e525c03e46dda2a2186dabee154e26780da96b2ac85a"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"integer","zh_from":"same-version-pgdoc"},"ManualEvidence":{"doc":{"anchor":"GUC-IO-WORKERS","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"io_workers","SourceDatabase":"center","Version":"18","Locale":"en","Title":"io_workers","Summary":"Selects the number of I/O worker processes to use. The default is 3. 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.","BodyHTML":"\u003cp\u003eSelects the number of I/O worker processes to use. The default is 3. 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.\u003c/p\u003e","SourceRevision":"wiki-repair-20261023:7e1d489032134803ceaec180038f00fa35362b11be481654acec97833aefb2c3","ContentHash":"46a5fe024642492d16874c710a281ecacc0b0c4814945f299785e8a7a8c170cc","Payload":{"description":"Selects the number of I/O worker processes to use. The default is 3. 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."}},"RequestedLocale":"en","Fallback":false,"Versions":["18"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}