io_max_concurrency

Definition PG 18 manual

Controls the maximum number of I/O operations that one process can execute simultaneously.

The default setting of -1 selects a number based on shared_buffers and the maximum number of processes (max_connections, autovacuum_worker_slots, max_worker_processes and max_wal_senders), but not more than 64.

This parameter can only be set at server start.

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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: 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.