effective_io_concurrency

Tells PostgreSQL how many storage I/O operations one session should expect to issue concurrently. It shapes asynchronous reads and, on supported systems, prefetch distance; it is not a global I/O limit.

Note

Fact — official short description: “Number of simultaneous requests that can be handled efficiently by the disk subsystem.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value—: Raw unit
Range , Value0 – 1000: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / I/O: Upstream classification
Latest boot value , Value16: 16

Lifecycle

Fact	Value
First observed	PG9.0 (research boundary)
Present in	PG9.0–19 Beta 3
Removed in	No
Introduction commit	Not asserted: predates the PG9.0 research boundary
Commit date	—
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.0–17	`1`	—	1
PG18–19 Beta 3	`16`	—	16

How it works

effective_io_concurrency tells one session how much storage concurrency it should try to exploit; it is not a cluster-wide queue cap. A tablespace option of the same name can override the session setting for data on that storage.

In PG10–17 it mainly controls prefetch distance for supported paths and platforms. The measured Linux-Docker boot value is 1, but unsupported platforms without effective posix_fadvise used 0 as the default; that platform condition must accompany any historical default claim.

PostgreSQL 18 integrates the setting with core asynchronous I/O, uses a boot default of 16, and allows 0 to disable asynchronous requests governed by this target. io_max_concurrency remains the separate per-process execution ceiling, and combine limits control bytes per request.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Start conservatively and measure read latency under concurrency. Fast point queries often gain less than bitmap or scan-heavy workloads, while a very high per-session value can multiply queue depth at high connection counts.
OLAP	Analytical scans and bitmap heap scans are stronger candidates for higher values. Benchmark sustained throughput and tail latency together, especially on network or high-IOPS storage.
Small nodes	Use the PG18 default or a modest value unless measurements show I/O stalls. A value of 200 is rarely justified on a small host merely because the disk is labeled SSD.

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	`200`	different	`200`
OLAP	`200`	different	`200`
CRIT	`200`	different	`200`
TINY	`200`	different	`200`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 200 (dcs); OLAP: PG9.0–19 Beta 3 = 200 (dcs); CRIT: PG9.0–19 Beta 3 = 200 (dcs); TINY: PG9.0–19 Beta 3 = 200 (dcs). Advice, pending human review — Editorial inference: Pigsty’s SSD branch assumes deep per-session read concurrency and prefetch are beneficial; that assumption requires device-level validation.

Common pitfalls

Treating this per-session target as a cluster-wide cap; many sessions can multiply outstanding I/O.
Calling 1 the unconditional PG10–17 upstream default even though unsupported platforms defaulted to 0.
Applying PG18 AIO behavior to older releases that used the setting chiefly for prefetch advice.
Using one global value for mixed-storage tablespaces instead of considering tablespace overrides.
Raising the target until device queueing increases latency for every session.

maintenance_io_concurrency · io_method · io_max_concurrency · io_combine_limit · random_page_cost · effective_cache_size