# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `user` | Settable by an ordinary user |
| Unit | — | Raw unit |
| Range | `0` – `1000` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Resource Usage / I/O | Upstream classification |
| Latest boot value | `16` | 16 |
{.fields meta="-"}

## Lifecycle {#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 {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.0–17 | `1` | — | 1 |
| PG18–19 Beta 3 | `16` | — | 16 |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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` |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`maintenance_io_concurrency`](/parameters/maintenance-io-concurrency/) · [`io_method`](/parameters/io-method/) · [`io_max_concurrency`](/parameters/io-max-concurrency/) · [`io_combine_limit`](/parameters/io-combine-limit/) · [`random_page_cost`](/parameters/random-page-cost/) · [`effective_cache_size`](/parameters/effective-cache-size/)

## References {#references}

- [PostgreSQL 19 Beta 3 — effective_io_concurrency](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-EFFECTIVE-IO-CONCURRENCY)
- [PostgreSQL 18 release notes: asynchronous I/O and new default](https://www.postgresql.org/docs/18/release-18.html)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)