{"Entry":{"collection":"guc","key":"io_method","name":"io_method","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":"17","status":"added","to":"18"}],"content_hash":"37cadd8a144208c47acd4b46f21d56a05727b0e06fc8f8023828a61c3fc78b26","context":"","default_changed_in":[],"default_history":[{"from":"18","to":"19","value":"worker"}],"editorial":{"advice":{"olap":"Sequential and bitmap-heavy analytical workloads are promising AIO candidates. Benchmark worker and io_uring with realistic scan concurrency, not just a single cold scan.","oltp":"Use worker as the compatibility baseline. Test io_uring only on a verified build and kernel, and keep it only if representative concurrent latency improves without destabilizing the storage queue.","small":"Worker is a safe default; sync can be a diagnostic fallback when worker overhead or platform constraints matter. Avoid spending scarce processes on excessive io_workers."},"mechanism":["worker sends eligible I/O through dedicated I/O worker processes; io_uring uses Linux io_uring and requires a build with liburing support; sync performs asynchronous-eligible operations synchronously. The upstream default is worker.","The PG18 AIO subsystem allows backends to queue multiple reads and can improve sequential scans, bitmap heap scans, vacuum, and other supported operations. It does not make every PostgreSQL I/O path asynchronous.","io_workers matters only when worker is selected. io_max_concurrency and the I/O combine limits control different dimensions of queue depth and request size, so method selection should be evaluated with them and with the storage stack."],"pitfalls":["The parameter does not exist before PostgreSQL 18.","Changing it requires a server restart.","io_uring requires operating-system and build support; the enum value alone does not provide that support.","io_workers has no effect unless io_method=worker.","AIO benefits only eligible paths and cannot compensate for an overloaded or poorly configured storage layer."],"references":[{"title":"PostgreSQL 19 Beta 4: io_method","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-IO-METHOD"},{"title":"PostgreSQL 18 release notes: asynchronous I/O subsystem","url":"https://www.postgresql.org/docs/18/release-18.html"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["io_workers","io_max_concurrency","io_combine_limit","io_max_combine_limit","effective_io_concurrency","maintenance_io_concurrency"],"summary":"io_method — Selects the method for executing asynchronous I/O. Observed in PG18–19 Beta 4; its last measured boot default is worker in PG19 Beta 4, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"18","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.409411+08:00","intro_commit":{"authored_at":"2025-03-17T18:51:33-04:00","discussion":["https://postgr.es/m/uvrtrknj4kdytuboidbhwclo4gxhswwcpgadptsjvjqcluzmah%40brqs62irg4dt"],"hash":"02844012b304ba80d1c48d51f6fe10bb622490cc","subject":"aio: Basic subsystem initialization","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=02844012b304ba80d1c48d51f6fe10bb622490cc"},"key":"io_method","last_version":"20","max_val":"","min_val":"","name":"io_method","position":185,"present_in":["18","19","20"],"short_desc":"Selects the method for executing asynchronous I/O.","short_desc_zh":"","source_rev":"english-manuals:e1dc166dab1d9f0d1da0d67a3b3cb5fe3f84077f8f7547800e2ed1041b76c368","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"io_method","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"io_method","SourceRevision":"english-manuals:e1dc166dab1d9f0d1da0d67a3b3cb5fe3f84077f8f7547800e2ed1041b76c368","Facts":{"boot_val":"worker","category":"Resource Usage / I/O","context":"postmaster","description":"Selects the method for executing asynchronous I/O. Possible values are: worker (execute asynchronous I/O using worker processes) io_uring (execute asynchronous I/O using io_uring, requires a build with --with-liburing / -Dliburing) sync (execute asynchronous-eligible I/O synchronously) The default is worker. This parameter can only be set at server start.","doc":{"anchor":"GUC-IO-METHOD","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":["sync","worker","io_uring"],"extra_desc":null,"lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"io_method","short_desc":"Selects the method for executing asynchronous I/O.","source":"pg-settings-source-snapshot","unit":null,"vartype":"enum"},"ManualEvidence":{"doc":{"anchor":"GUC-IO-METHOD","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"io_method","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"io_method","Summary":"","BodyHTML":"\u003cp\u003e选择执行异步 I/O 的方法。可能的值有：\u003c/p\u003e\u003cdiv\u003e\u003cul\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003eworker\u003c/code\u003e（使用工作进程执行异步 I/O）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003eio_uring\u003c/code\u003e（使用 io_uring 执行异步 I/O，需要以 \u003ca href=\"/docs/18/install-make.html#CONFIGURE-OPTION-WITH-LIBURING\" rel=\"nofollow\"\u003e\u003ccode\u003e--with-liburing\u003c/code\u003e\u003c/a\u003e / \u003ca href=\"/docs/18/install-meson.html#CONFIGURE-WITH-LIBURING-MESON\" rel=\"nofollow\"\u003e\u003ccode\u003e-Dliburing\u003c/code\u003e\u003c/a\u003e 进行构建）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode\u003esync\u003c/code\u003e（将可异步执行的 I/O 同步执行）\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e默认值为 \u003ccode\u003eworker\u003c/code\u003e。\u003c/p\u003e\u003cp\u003e此参数只能在服务器启动时设置。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"8c40ddd18fc9ac73f0cfc89a765de14d693aa6710519a0488eab32686f79c6cd","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e选择执行异步 I/O 的方法。可能的值有：\u003c/p\u003e\u003cdiv class=\"itemizedlist\"\u003e\u003cul\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003eworker\u003c/code\u003e（使用工作进程执行异步 I/O）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003eio_uring\u003c/code\u003e（使用 io_uring 执行异步 I/O，需要以 \u003ca href=\"/docs/18/install-make.html#CONFIGURE-OPTION-WITH-LIBURING\"\u003e\u003ccode class=\"option\"\u003e--with-liburing\u003c/code\u003e\u003c/a\u003e / \u003ca href=\"/docs/18/install-meson.html#CONFIGURE-WITH-LIBURING-MESON\"\u003e\u003ccode class=\"option\"\u003e-Dliburing\u003c/code\u003e\u003c/a\u003e 进行构建）\u003c/p\u003e\u003c/li\u003e\u003cli\u003e\u003cp\u003e\u003ccode class=\"literal\"\u003esync\u003c/code\u003e（将可异步执行的 I/O 同步执行）\u003c/p\u003e\u003c/li\u003e\u003c/ul\u003e\u003c/div\u003e\u003cp\u003e默认值为 \u003ccode class=\"literal\"\u003eworker\u003c/code\u003e。\u003c/p\u003e\u003cp\u003e此参数只能在服务器启动时设置。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}