maintenance_io_concurrency

Definition PG 18 manual

Similar to effective_io_concurrency, but used for maintenance work that is done on behalf of many client sessions.

The default is 16. This value can be overridden for tables in a particular tablespace by setting the tablespace parameter of the same name (see ALTER TABLESPACE).

How it works

maintenance_io_concurrency is the per-maintenance-operation target for storage concurrency used by work performed on behalf of many clients. A tablespace option of the same name can override it for that storage; it is neither a cluster-wide device cap nor a memory allocation.

In PG13–17 it chiefly controls maintenance prefetch on supported systems. The measured Linux-Docker boot value is 10, while unsupported platforms without effective prefetch-advice support defaulted to 0; those releases do not have the PG18 core-AIO execution model.

PostgreSQL 18 integrates the target with core AIO and uses a boot default of 16. io_max_concurrency separately clamps simultaneous execution by one process, io_method chooses the execution mechanism, and combine limits control bytes per request. Its user context permits scoped runtime changes.

Operational considerations

Calling 10 the unconditional PG13–17 default when unsupported platforms used 0.

Back-projecting PG18 core-AIO semantics into PG13–17 prefetch behavior.

Treating the per-operation target as a cluster or device-wide cap.

Confusing concurrency with io_combine_limit's bytes-per-request dimension.

Using one value across tablespaces with materially different storage.

Workload guidance

OLAP: Higher maintenance concurrency can shorten eligible scans or vacuum work on high-latency, high-IOPS storage, but it can also deepen the queue seen by analytical queries. Benchmark maintenance completion time and mixed-workload latency together; it does not change request size.

OLTP: For PG13–17, tune this as a maintenance-prefetch target only on supported storage; for PG18, tune it as an AIO concurrency target. Measure foreground tail latency while VACUUM or other eligible maintenance runs, and use a tablespace override for heterogeneous storage.

SMALL: Use the version- and platform-appropriate default unless maintenance is demonstrably I/O-stalled.