io_workers

Definition PG 18 manual

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.

How it works

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.

Operational considerations

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.

Workload guidance

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.