io_max_workers

io_max_workers — Maximum number of I/O worker processes, for io_method=worker. Observed in PG19 Beta 3; its last measured boot default is 8 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Maximum number of I/O worker processes, for io_method=worker.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value1 – 32: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / I/O: Upstream classification
Latest boot value , Value8: 8

Lifecycle

Fact	Value
First observed	PG19 Beta 3
Present in	PG19 Beta 3
Removed in	No
Introduction commit	`d1c01b79d4ae` — aio: Adjust I/O worker pool automatically.
Commit date	2026-04-08
Discussion	thread 1

Default history

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

How it works

PostgreSQL describes io_max_workers as follows: “Maximum number of I/O worker processes, for io_method=worker.” A configuration reload applies the value to the server without a full restart. The atlas measures it in PG19 Beta 3; boot_val is the compiled or initialized baseline, not proof of a running cluster’s effective setting.

These controls govern the elastic background-worker pool used only when io_method is worker. io_min_workers keeps warm capacity, io_max_workers caps the pool, io_worker_launch_interval damps short bursts, and io_worker_idle_timeout lets unused workers retire; they do not raise a backend’s separate io_max_concurrency ceiling.

Read it together with io_min_workers, io_worker_idle_timeout, io_worker_launch_interval, io_method. Check SHOW and pg_settings on the target server, verify the source and pending_restart fields, and compare workload, logs, and resource metrics before and after any change.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Benchmark with the production storage stack and concurrency. Optimize tail latency and queue depth, not only average throughput, and retain capacity for WAL, checkpoints, and foreground reads.
OLAP	Use representative scans, prefetch, and spill phases. Increase concurrency or worker capacity only while throughput rises without unacceptable CPU overhead, memory pressure, or storage saturation.
Small nodes	Prefer auto or the upstream worker limits. Validate with pg_test_timing or I/O statistics as applicable; a larger pool on a small node can add context switching without useful parallelism.

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	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG19 Beta 3 unmodified; OLAP: PG19 Beta 3 unmodified; CRIT: PG19 Beta 3 unmodified; TINY: PG19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Treating the measured boot_val for io_max_workers as proof of the effective value on an initialized or managed cluster.
Applying a change as though it were immediate while pg_settings reports sighup context.
Changing this setting in isolation without checking the linked limits, observability, and rollback path.
Depending on beta behavior in production without retesting the PostgreSQL 19 final release.

io_min_workers · io_worker_idle_timeout · io_worker_launch_interval · io_method · io_max_concurrency · io_combine_limit