{"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"}],"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"],"short_desc":"Selects the number of I/O worker processes to use.","short_desc_zh":"","source_rev":"english-manuals:ccd93e03547fcf037147970cb0bed786cd5d118345b5eb08d0ab5e0d86da3f92","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"io_workers","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"io_workers","SourceRevision":"english-manuals:ccd93e03547fcf037147970cb0bed786cd5d118345b5eb08d0ab5e0d86da3f92","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.","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","unit":null,"vartype":"integer"},"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":"pgweb","Version":"18","Locale":"zh-Hans","Title":"io_workers","Summary":"","BodyHTML":"\u003cp\u003e选择要使用的 I/O 工作进程数量。默认值为 3。此参数只能在 \u003ccode\u003epostgresql.conf\u003c/code\u003e文件中或服务器命令行中设置。\u003c/p\u003e\u003cp\u003e仅当\u003ca href=\"/docs/18/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":"faf3f5cd1ebc0831e1f966bb961e7ab9edfb6109ba89eb7ac0b3f18ec3877ec5","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e选择要使用的 I/O 工作进程数量。默认值为 3。此参数只能在 \u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e文件中或服务器命令行中设置。\u003c/p\u003e\u003cp\u003e仅当\u003ca href=\"/docs/18/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":["18"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}