io_max_concurrency

io_max_concurrency — Max number of IOs that one process can execute simultaneously. Observed in PG18–19 Beta 3; its last measured boot default is -1 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: “Max number of IOs that one process can execute simultaneously.”

Identity

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

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	`-1`	—	-1

How it works

io_max_concurrency is a PostgreSQL 18 server-start ceiling on the number of I/O operations that one process may execute simultaneously. It is per process, not a reservation and not a cluster-wide cap.

The default -1 asks PostgreSQL to derive a value from shared_buffers and configured process maxima, capped at 64. Because many backends and workers can each reach their own ceiling, possible cluster-wide outstanding I/O can be much larger.

effective_io_concurrency and maintenance_io_concurrency are workload targets below this ceiling; io_method chooses the execution mechanism, and combine limits control bytes per request. Changing io_max_concurrency requires a restart.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Leave -1 until measurements show the automatic per-process ceiling constrains eligible AIO. If setting it explicitly, multiply the value across concurrently active processes and test device queueing plus tail latency after the required restart.
OLAP	Raise the per-process ceiling only when one scan or maintenance process cannot keep high-IOPS storage busy and the target-concurrency settings are already appropriate. Compare outstanding-operation counts, throughput, and latency; this parameter does not change request size.
Small nodes	Prefer -1. An explicit high ceiling is multiplied by concurrent processes and can overwhelm a small device even though no single process exceeds its configured limit.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Treating the per-process ceiling as a cluster-wide I/O limit.
Reading -1 as unlimited rather than automatic sizing capped at 64.
Calling the ceiling reserved capacity; it permits concurrency but does not preallocate I/O slots.
Confusing operation count with io_combine_limit’s bytes per request.
Changing the value without a restart or without multiplying exposure across processes.

io_method · io_workers · effective_io_concurrency · maintenance_io_concurrency · io_combine_limit · max_connections