io_method

io_method — Selects the method for executing asynchronous I/O. Observed in PG18–19 Beta 3; its last measured boot default is worker in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Selects the method for executing asynchronous I/O.”

Identity

Type , Valueenum: Upstream pg_settings type
Context , Valuepostmaster: Requires a server restart
Unit , Value—: Raw unit
Range , Value—: Raw limits in the last observed version
Enum values , Valuesync, worker, io_uring: — for non-enum types
Category , ValueResource Usage / I/O: Upstream classification
Latest boot value , Valueworker: worker

Lifecycle

Fact	Value
First observed	PG18
Present in	PG18–19 Beta 3
Removed in	No
Introduction commit	`02844012b304` — aio: Basic subsystem initialization
Commit date	2025-03-17
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG18–19 Beta 3	`worker`	—	worker

How it works

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	`worker`	same as boot	`{{ pg_effective_io_method }}`
OLAP	`worker`	same as boot	`{{ pg_effective_io_method }}`
CRIT	`worker`	same as boot	`{{ pg_effective_io_method }}`
TINY	`worker`	same as boot	`{{ pg_effective_io_method }}`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG18–19 Beta 3 = worker (dcs); OLAP: PG18–19 Beta 3 = worker (dcs); CRIT: PG18–19 Beta 3 = worker (dcs); TINY: PG18–19 Beta 3 = worker (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: Pigsty selects the portable PG18 AIO baseline while leaving io_uring as an explicit operator choice.

Common 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.

io_workers · io_max_concurrency · io_combine_limit · io_max_combine_limit · effective_io_concurrency · maintenance_io_concurrency