Parameter · Resource Usage / I/O
io_workers
Number of IO worker processes, for io_method=worker.
- Default:
3 - Type: integer
- Range: 1 … 32
- Applies: Reload
In plain words
With the default io_method = worker, a few dedicated processes perform reads on behalf of all sessions. If there are too few, requests queue up waiting for a free worker. Changing it only needs a reload.
For DBAs and operators
New in PostgreSQL 18; range 1–32; no effect with other io_methods. I/O workers are auxiliary processes (not taken from max_worker_processes). Each worker performs one synchronous read at a time, so the total reads in flight server-wide are bounded by io_workers. On machines with fast storage and many concurrent scans, 3 is often too low; a starting point is a quarter to a half of the CPU cores (e.g. 8–16), then check:
-- workers always busy = too few
SELECT pid, wait_event_type, wait_event, state
FROM pg_stat_activity WHERE backend_type = 'io worker';
SELECT count(*) FROM pg_aios WHERE state = 'SUBMITTED';Backends stuck in AioIoCompletion while all io workers are busy is the signal to add workers (or to try io_uring).
How to change it
Change in postgresql.conf or ALTER SYSTEM, then run SELECT pg_reload_conf().