# Should I switch Postgres 18 io_method to io_uring?

> **Quick answer:** Stay on `worker` unless three things are true: your build has
> liburing, your container or host policy allows the io_uring syscalls, and a
> benchmark on your own workload shows a gain. On the workload measured here
> there was no gain, but that is one workload. The read improvement that did show
> up, on both methods and repeatably, came from `io_combine_limit`, which
> PostgreSQL 18 already defaults to 128kB and which you get without choosing a
> method. Everything measured here was run on PostgreSQL 18.6 in `postgres:18.6`
> containers on one 8 vCPU Linux 6.17.0-1022-azure host under Docker 29.1.3, on
> 2026-09-19 for the configuration and syscall findings and on 2026-09-20 for
> every number that came off a benchmark.

## What is the problem?

PostgreSQL 18 added an asynchronous I/O subsystem, and `io_method` chooses how
that I/O is executed.

The word "asynchronous-eligible" matters. `io_method` does not route every read
and write in the server through the chosen mechanism. The
[PostgreSQL 18 release announcement](https://www.postgresql.org/about/news/postgresql-18-released-3142/)
names the scope: "AIO operations supported in PostgreSQL 18 include sequential
scans, bitmap heap scans, and vacuum." Write-ahead log writes and ordinary dirty
buffer writeback are not on that list. If your workload is point lookups on a
cached working set, changing `io_method` affects a setting that your queries
barely reach.

The three values, quoted from the
[PostgreSQL 18 resource configuration documentation](https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-METHOD):

| value | what the [PostgreSQL 18 resource configuration documentation](https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-METHOD) says |
|---|---|
| `worker` | "execute asynchronous I/O using worker processes". The default. |
| `io_uring` | "execute asynchronous I/O using io_uring, requires a build with `--with-liburing` / `-Dliburing`" |
| `sync` | "execute asynchronous-eligible I/O synchronously" |

`sync` is not "PostgreSQL 17 again", although the [PostgreSQL 18 release announcement](https://www.postgresql.org/about/news/postgresql-18-released-3142/)
invites that reading when it says the `sync` setting lets you "maintain the
current PostgreSQL behavior". Measured on 2026-09-20 on PostgreSQL 18.6 in a
`postgres:18.6` container with `io_method=sync`, on a sequential scan of a
2528 MB table with the host page cache evicted first, `pg_aios` was populated
throughout: 169 of 200 tight-loop samples showed an I/O in flight, and the
most ever in flight was 1. The AIO machinery is still in the path; it just
completes the I/O inline and one at a time. What does revert is the wait event
name, which goes back to the pre-18 `IO / DataFileRead`. Sampling that same
PostgreSQL 18.6 `postgres:18.6` container on 2026-09-20 every 2 ms during that
scan, 1461 of 2000 samples caught the backend in exactly that wait.

## The three gates, in order

Before benchmarking anything, answer these. Two of them are yes-or-no and
neither is about performance.

### 1. Was your PostgreSQL built with liburing?

`io_uring` is a build option, not a runtime capability of Linux. A recent kernel
is not enough. Check the build:

<!-- sql-check: pg 18+ -->
```sql
SELECT setting LIKE '%--with-liburing%' AS has_liburing
FROM pg_config()
WHERE name = 'CONFIGURE';
```

Check `CONFIGURE`, not `LIBS`. On the official `postgres:18.6` image, measured
2026-09-19, `CONFIGURE` contains `'--with-liburing'` and `LIBS` does not mention
uring at all, so a `LIBS` check would report a false negative on a build that
supports it.

That image is eligible. The failure in the next section is often blamed on
the build, but the build is not the cause.

`io_uring` is also Linux-only. On macOS, Windows or BSD, `worker` is the only
asynchronous option and this page is not a tuning choice you have.

### 2. Does your container or host policy allow the syscalls?

This is the gate that catches people, and its error message points somewhere
else.

Measured on 2026-09-19 on PostgreSQL 18.6, in a `postgres:18.6` container
started under Docker 29.1.3 on Linux 6.17.0-1022-azure with the default seccomp
profile:

```
FATAL:  could not setup io_uring queue: Operation not permitted
HINT:   Check if io_uring is disabled via /proc/sys/kernel/io_uring_disabled.
```

The container exited with status 1. The server does not fall back to another
method; it fails to boot.

The hint is misleading here. On this host `/proc/sys/kernel/io_uring_disabled`
was `0`, so the kernel's global disable switch was not the cause. The cause is
one level up, and it can be isolated exactly rather than inferred:

[Docker's default seccomp profile](https://github.com/moby/profiles/blob/main/seccomp/default.json)
allows 426 distinct syscall names with a `defaultAction` of `SCMP_ACT_ERRNO`, and not one
of those 426 names contains `io_uring`. Anything not on the list returns an
error, which is the `Operation not permitted` above.

The test is a one-line difference. Take that exact profile, add three syscall
names and change nothing else:

```json
{ "names": ["io_uring_setup", "io_uring_enter", "io_uring_register"],
  "action": "SCMP_ACT_ALLOW" }
```

Measured on 2026-09-19 with the same image, same host, same kernel, same profile
file:

| profile | result |
|---|---|
| stock default profile, passed explicitly | `FATAL: could not setup io_uring queue`, container exited 1 |
| same file plus those three names | started, `SHOW io_method` returned `io_uring` |

The change that isolates the cause is also the fix. Do not reach for
`seccomp=unconfined`. That removes the syscall filter from the entire container
to enable one database setting, and it is a larger change than the one actually
required. A profile that adds three syscalls to the default is the least-privilege
version of the same fix:

```
docker run --security-opt seccomp=./io-uring-seccomp.json ...
```

Under Kubernetes the same question arrives as a `seccompProfile` on the pod
spec, using a profile installed on the node, and it is a cluster policy
conversation rather than a database one. Either way, confirm it in the same
image and runtime class you will restart in production, because `io_method` is
`postmaster` context: a configuration that the runtime rejects is an outage at
the next restart, not an error at the next reload.

### 3. Does it actually help your workload?

The rest of this page answers that. For the workload measured here, the answer
was no.

## What is set by default

Measured on 2026-09-19 on PostgreSQL 18.6 in a stock `postgres:18.6` container:

<!-- sql-check: pg 18+ -->
```sql
SELECT name, setting, boot_val, context
FROM pg_settings
WHERE name LIKE 'io_%' OR name IN ('effective_io_concurrency', 'maintenance_io_concurrency')
ORDER BY name;
```

```
          name             setting  boot_val   context
 effective_io_concurrency   16       16        user
 io_combine_limit           16       16        user
 io_max_combine_limit       16       16        postmaster
 io_max_concurrency         64       -1        postmaster
 io_method                  worker   worker    postmaster
 io_workers                 3        3         sighup
 maintenance_io_concurrency 16       16        user
```

`io_method` is `postmaster` context, so changing it needs a full restart.
`io_workers` is `sighup`, so the number of I/O workers changes with a reload,
which makes tuning the default method cheaper than switching away from it.
And `io_max_concurrency` has a `boot_val` of `-1` where its setting is 64. The
[documentation for `io_max_concurrency`](https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-MAX-CONCURRENCY)
says `-1` "selects a number based on shared_buffers and the maximum number of
processes .. but not more than 64", so the number you see is
derived from your configuration rather than a fixed default.

I/O workers do not come out of your `max_worker_processes` budget. This is
worth checking, because I/O workers are background
processes and the budget is shared by parallel query, parallel maintenance,
logical replication and extensions. Measured on 2026-09-19 on PostgreSQL 18.6 in
a `postgres:18.6` container with `max_worker_processes=4` and
`max_parallel_workers_per_gather=4`, against a table
forced to a parallel plan:

| `io_workers` | io worker processes running | parallel workers launched |
|---|---|---|
| 1 | 1 | 3 of 4 planned |
| 4 | 4 | 3 of 4 planned |

Four I/O workers plus three parallel workers is seven against a budget of four,
so they are not drawn from the same pool. The one parallel worker that never
launches in either row is the logical replication launcher holding a slot, which
is unrelated to `io_method` and is there at `io_workers=1` too.

## How do I confirm which one is running?

There are three layers, and each answers a different question.

**Configured method.** `SHOW io_method` is the authoritative check, because it
reports what the server is set to:

<!-- sql-check: pg 18+ -->
```sql
SHOW io_method;
```

The process list corroborates it. With `io_method = worker` there are
`io worker` processes; with `io_uring` there are no `io worker` processes.
Measured on 2026-09-19 on the two `postgres:18.6` containers, 3 and 0. Read
"none" narrowly: it means no
PostgreSQL I/O worker processes, not that nothing is doing I/O.

One trap: `SHOW io_workers` returned `3` on the `io_uring` container as well,
because the parameter still has a value. The
[documentation for `io_workers`](https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-WORKERS)
is explicit that it "Only has an effect if `io_method` is set to `worker`". A non-zero `io_workers`
is not evidence that the worker method is in use.

**In-flight I/O.** PostgreSQL 18 added `pg_aios`, a point-in-time view of AIO
handles:

<!-- sql-check: pg 18+ -->
```sql
SELECT pid, state, operation, off, length, target, target_desc
FROM pg_aios
LIMIT 10;
```

It is not io_uring-specific and it is not usually empty under load. Sampled in a
tight loop on 2026-09-20 during a single-stream scan of the 2528 MB table on
PostgreSQL 18.6, in the two `postgres:18.6` containers described below, with the
host page cache evicted first so the reads were real: 396 of 400 samples on the
`io_uring` container and 400 of 400 on the `worker` container returned rows,
with a maximum of 5 I/Os in flight on each. Occupancy depends on storage
latency, queue depth and how fast you sample, so read it as a view of depth at
an instant and not as a throughput number.

What it does not tell you is whether those reads reach a device. The same loop
on the same two containers the same day, against scans served entirely from the
host page cache, returned the same 400 of 400 and 396 of 400 with the same
maximum of 5. PostgreSQL queues the reads either way; a cached one just
completes sooner. `pg_aios` is a view of the queue, not of the disk.

**Waits.** The AIO wait events split across two categories, which changes what
they can tell you:

<!-- sql-check: pg 18+ -->
```sql
SELECT type, name, description
FROM pg_wait_events
WHERE name LIKE 'Aio%'
ORDER BY type, name;
```

Measured on 2026-09-19 on PostgreSQL 18.6 in a `postgres:18.6` container:

```
  type  |           name           |                   description
--------+--------------------------+---------------------------------------------------------
 IO     | AioIoCompletion          | Waiting for another process to complete IO
 IO     | AioIoUringExecution      | Waiting for IO execution via io_uring
 IO     | AioIoUringSubmit         | Waiting for IO submission via io_uring
 LWLock | AioUringCompletion       | Waiting for another process to complete IO via io_uring
 LWLock | AioWorkerSubmissionQueue | Waiting to access AIO worker submission queue
```

`AioUringCompletion` and `AioWorkerSubmissionQueue` are `LWLock` waits, not `IO`
waits. Sorting by `wait_event_type` and treating everything AIO-shaped as I/O
will put contention in the wrong bucket.

Sampled waits distinguish the two methods in practice. Measured on 2026-09-20
on PostgreSQL 18.6 in the two `postgres:18.6` containers on Linux
6.17.0-1022-azure under Docker 29.1.3, sampling `pg_stat_activity` from inside
the server during repeated cold sequential scans, 8000 samples per method at a
mean interval of 2.17 ms:

| method | wait | samples | share |
|---|---|---|---|
| `worker` | `IO / AioIoCompletion` | 4784 | 59.8% |
| `worker` | no wait, backend running | 3216 | 40.2% |
| `io_uring` | `IO / AioIoUringExecution` | 2739 | 34.2% |
| `io_uring` | `IO / AioIoUringSubmit` | 2410 | 30.1% |
| `io_uring` | no wait, backend running | 2851 | 35.6% |

Each method's rows sum to its own 8000 samples, so the shares are of that
method's samples and not of the 16,000 together. `worker` shows one AIO wait and
`io_uring` shows two. That follows from how each mechanism works and says
nothing about which is better.

Two cautions. A wait sample is an instant, not an attribution: a query can
complete every relevant I/O between two samples, so a method whose waits are
short and frequent is undersampled by exactly the same instrument that catches a
method whose waits are long. And these shares depend entirely on the reads being
real. Run on 2026-09-20 on PostgreSQL 18.6 in those same `postgres:18.6`
containers against scans served from the host page cache rather than from the
device, the same sampling caught the backend running rather than waiting in 7962
of 8000 samples under `worker` and 7368 of 8000 under `io_uring`, 99.5 and
92.1 percent, because there was almost nothing to wait for. If your wait profile
shows the backend never blocked on I/O, check that it is reading anything before
you conclude the storage is fast.

No `LWLock / BufferMapping` sample appeared in either method in the cold run. The
sampler filtered on nothing but the backend running the scan and recorded
whatever `wait_event_type` it found, it recorded `IO` waits in both methods, and
in the cached run above it recorded one `LWLock / AioWorkerSubmissionQueue`
sample, so an `LWLock` wait would have been caught had one occurred. One stream
against one table is not where buffer mapping contends. Use `SHOW io_method` for what
is configured and treat waits as diagnostic evidence about where time is going.

## Does it go faster?

**Measured against:** run on 2026-09-20 on one host, 8 vCPU, 62 GB RAM, Linux
6.17.0-1022-azure, Docker 29.1.3, storage on `sda`. Two `postgres:18.6`
containers on separate named volumes, one `io_method=worker` and one `io_uring`,
both `shared_buffers=128MB`, both `-m 1g`, both with identical
`effective_io_concurrency=16`, `io_combine_limit=128kB` and
`io_max_concurrency=64`, and both with `max_parallel_workers_per_gather=0` so a
plan change could not affect the comparison.

**The table.** Built from this one statement, run identically in both
containers:

```sql
CREATE TABLE bench AS
SELECT g AS id, repeat('x', 200) AS pad
FROM generate_series(1, 11000000) g;
```

That gives 11,000,000 rows in 2,650,800,128 bytes, which is 323,584 blocks and
2528 MB, the same in both arms. The `pad` column makes the table large enough
that a scan of it has to reach storage.

**The statement the timings come from.** Every figure below is the
`Execution Time` line reported by this, run through `psql` inside the container:

```sql
EXPLAIN (ANALYZE, BUFFERS) SELECT count(*) FROM bench;
```

`\timing` and the shell's `time` are not used, because they include connection
setup and the round trip, which is noise of the same order as the difference
being looked for.

**Making the reads physical without root, and the trap on the way there.** A
restart empties `shared_buffers` and leaves the host page cache alone, so a
restart-only benchmark measures memory and reports it as disk. Dropping the page
cache with `sync; echo 3 > /proc/sys/vm/drop_caches` needs root on the host and
affects every other process on it.

The tempting way around that is the container memory limit. Run each PostgreSQL
18.6 `postgres:18.6` container with `-m 1g`, and under cgroup v2 the page cache
for files it reads is charged to that limit, so on 2026-09-20 a 2528 MB table
could not stay resident in the charge. That is true
about the charge and false about the cache. Dropping the charge does not evict
the page: it stays in host RAM, uncharged to anyone, and the next read is a
memory read. Measured on 2026-09-20 on PostgreSQL 18.6 in a `postgres:18.6`
container capped at `-m 1g` and freshly restarted, a scan the server reported as
`read=323584`, which is the whole 2528 MB table, moved the host's
`/proc/diskstats` sectors-read counter by 216 sectors, 108 kB, and moved the
container's own `/sys/fs/cgroup/io.stat` `rbytes` by zero. The table was served
out of host RAM in its entirety, and both the restart and the memory cap were
satisfied the whole time.

What does work, without root, is `POSIX_FADV_DONTNEED`, which needs only
permission to open the file. Walking the data directory and calling it on every
file between rounds evicts that instance's pages from the host cache and leaves
every other process alone. Measured on the same PostgreSQL 18.6 `postgres:18.6`
container on 2026-09-20, the
same scan then moved `/proc/diskstats` by 5,185,864 sectors, 2532 MB, and cgroup
`rbytes` by 2528 MB against a 2528 MB table, and took 5354 ms where the cached
version of the identical statement took 3118 ms.

This is still not a fully cold device. Storage controller cache, device cache
and the hypervisor are all still there, and this host was not dedicated.

**The equivalence check.** At one stream, on 2026-09-20 on PostgreSQL 18.6 in
those two `postgres:18.6` containers, every round in both arms reported
`read=323584 hit=0` and a container `rbytes` delta of 2528 MB, with one
exception: round 3 on `dbg-io-a`, the 5369 ms round, read 2538 MB. That is 10 MB
of other traffic on the same volume in the same window, not a different amount
of table. The block count alone is necessary and not sufficient,
because PostgreSQL's counters cannot tell a physical read from a page cache hit,
which is exactly how the version above went wrong. `rbytes` is what settles it:
it is the kernel's count of bytes this container pulled off the block device, and
it matches the table.

**Single-stream scan, 12 rounds. Each round restarts the container, evicts that
volume's pages from the host cache, then scans once.** The order of the two arms
alternates per round so a first-scan-after-restart effect cannot land on the same
arm every time. Measured on 2026-09-20 on PostgreSQL 18.6 in the `postgres:18.6`
containers `dbg-io-a` and `dbg-io-b`:

| arm | rounds | median |
|---|---|---|
| `io_uring` | 11 of 12: 5312 to 5394 ms | 5347 ms |
| `worker` | 12 of 12: 5320 to 5369 ms | 5336 ms |
| `io_uring`, round 2 | 10,775 ms | reported, not used |

The 11 ms between the two medians is 0.2 percent of the `worker` median, and the
spread within a single arm is 82 ms, so it is smaller than the noise it sits in.
The one round at 10,775 ms is round 2 on `dbg-io-a`, and it is not the round
that read 2538 MB. On 2026-09-20 on that PostgreSQL 18.6 `postgres:18.6`
container it read 323,584 blocks and 2528 MB off the device, the same as every
round except round 3, so it is host contention and not more work.

**Eight concurrent copies of the same scan, 6 rounds, same protocol.** Measured
on 2026-09-20 on PostgreSQL 18.6 in the same two `postgres:18.6` containers.
Queue depth is the condition under which the submission mechanism should matter
most, so this is the arm that would show a difference if one existed here. The
figure per round is the slowest of the eight `Execution Time` values, which is
when the whole batch finished:

| arm | 6 rounds | median |
|---|---|---|
| `io_uring` | 9003 to 10,771 ms | 10,455 ms |
| `worker` | 9780 to 10,844 ms | 10,680 ms |

The two arms are not as tightly matched here as at one stream, and that matters
more than the 225 ms between the medians. On 2026-09-20 on PostgreSQL
18.6 in those `postgres:18.6` containers, with eight sessions sharing one
`shared_buffers`, per-session block counts ranged from 314,193 to 320,396 against
a 323,584-block table, and device reads per round ranged from 2582 MB to 3756 MB
as blocks were evicted under pressure and fetched again. Read these two rows as
overlapping ranges, not as a difference.

**The control.** The single-stream test was run again with the methods
on the opposite sides: same two containers, same two volumes, same 12 rounds,
same alternating order, same eviction between rounds, `io_method` swapped between
them. Measured on 2026-09-20 on PostgreSQL 18.6, both `postgres:18.6` containers
recreated with identical settings so the only difference between the arms was
`io_method`.

| run | container, volume | method | rounds | median |
|---|---|---|---|---|
| first | `dbg-io-a`, `dbg-io-va` | `io_uring` | 11 of 12: 5312 to 5394 ms | 5347 ms |
| first | `dbg-io-b`, `dbg-io-vb` | `worker` | 5320 to 5369 ms | 5336 ms |
| after the swap | `dbg-io-a`, `dbg-io-va` | `worker` | 5324 to 5370 ms | 5338.5 ms |
| after the swap | `dbg-io-b`, `dbg-io-vb` | `io_uring` | 5314 to 5354 ms | 5333 ms |

Every round of the swapped run, on 2026-09-20 on PostgreSQL 18.6 in those
`postgres:18.6` containers, reported `read=323584 hit=0` and 2528 MB off the
device, the same as the first, so both runs did the same physical work. The
swapped run has no round to set aside.

Across those two 2026-09-20 runs on PostgreSQL 18.6 in the same `postgres:18.6`
containers, the gap is 11 ms in the first and 5.5 ms in the second, and it points
the other way the second time. Both are inside the 82 ms that one arm covers
between its own fastest and slowest round. There is no difference here to attribute to
either the method or the container.

**What the cache story was worth.** The same three arms were run first with the
restart and the memory cap alone, no eviction, which is the protocol that looks
careful and measures host RAM. On 2026-09-20, on PostgreSQL 18.6 in the same two
`postgres:18.6` containers, `io_uring` had a median of 3209 ms over rounds 2 to
12 and `worker` a median of 2416 ms. That is 793 ms, 33 percent of the `worker`
median, and it would have
published as a large and consistent `io_uring` penalty. Every round of it
reported `read=323584 hit=0`, so the block-count check passed the whole time.
The entire effect was that one method is better than the other at scanning
memory, which is not what anybody is choosing `io_method` for.

**What this supports, and what it does not.** On this host, on a sequential scan
of one table, at one stream and at eight, `io_method` made no difference that
survived a control. It does not support "io_uring is not worth it". PostgreSQL's
own [PostgreSQL 18 release announcement](https://www.postgresql.org/about/news/postgresql-18-released-3142/)
reports "performance gains of up to 3x in certain scenarios", and nothing here contradicts that: this was a single-table
sequential scan on cloud block storage, which is close to the case where
throughput is bounded by the device rather than by how the read was submitted.

If you want a number for your own system, reuse the protocol that produced
these: identical settings on both arms, interleaved rounds with the order
alternated, the reads proven physical by the kernel's own byte counter every
round rather than by PostgreSQL's, and a swap control before you believe the
direction. The order matters. Until the reads are real, the swap control has
nothing to control for, and the block-count check will tell you everything is
fine.

## What to change instead

**`io_combine_limit` is worth more than `io_method` here, and 18 already sets it
well.** It controls how much adjacent data one read request covers. The
[documentation for `io_combine_limit`](https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-COMBINE-LIMIT),
read on 2026-09-19, says "The default is 128kB", and `pg_settings` reports the same
value as `16`, because the setting is in blocks and a block is 8kB. Both numbers
describe the same default.

There is nothing here to turn up. The setting explains where the 18 read
improvement comes from, and what to check is that nothing in your
configuration has turned it down. That same
[documentation for `io_combine_limit`](https://www.postgresql.org/docs/18/runtime-config-resource.html#GUC-IO-COMBINE-LIMIT)
notes it is capped by `io_max_combine_limit`, a postmaster setting, "so both may
need to be raised to increase the I/O size".

What combining is worth, measured on 2026-09-20 on PostgreSQL 18.6 on Linux
6.17.0-1022-azure, 8 vCPU, Docker 29.1.3, in the same two `postgres:18.6`
containers on the same 2528 MB table, on the same cold-read protocol as the
`io_method` arms above, by setting it to 8kB against the 128kB default with
`pg_stat_io` reset immediately before each scan:

| `io_combine_limit` | read operations | bytes read |
|---|---|---|
| 8kB | 323,619 | 2,651,086,848 |
| 128kB | 20,263 | 2,651,086,848 |

The same bytes, to the byte, in close to one sixteenth as many operations, which is
the ratio of the two settings. Every one of those 2026-09-20 runs, on
PostgreSQL 18.6 in those `postgres:18.6` containers, pulled 2528 MB off the
device.

And what it does to the clock, measured on 2026-09-20 on PostgreSQL 18.6 in the
same `postgres:18.6` containers, four pairs per method:

| method | 8kB | 128kB |
|---|---|---|
| `io_uring` | 6043, 6052, 6052, 6079 ms | 5322, 5341, 5343, 5363 ms |
| `worker` | 5707, 5711, 5772, 5774 ms | 5329, 5340, 5356, 5372 ms |

On 2026-09-20, on PostgreSQL 18.6 in those `postgres:18.6` containers, the 128kB
default was faster in all eight pairs: at the medians, 6052 ms to 5342 ms on
`io_uring`, a saving of 710 ms which is 11.7 percent of the 8kB median, and
5741.5 ms to 5348 ms on `worker`, a saving of 393.5 ms which is 6.9 percent. That is a larger and far more repeatable effect than anything
`io_method` did here. The read path improvement in 18 that shows up on a
sequential scan is read combining, and you get it without choosing a method.

One thing in that table is worth noticing and not worth concluding from. At the
128kB default the two methods are indistinguishable, as they were in every arm
above. At 8kB they are not: on 2026-09-20, on PostgreSQL 18.6 in those
`postgres:18.6` containers, `worker` is 310.5 ms ahead of `io_uring` at the
medians, 5.1 percent of the `io_uring` median. Sixteen times as many operations
is where a per-operation submission cost would show up if one exists. In the
swap control above, run on 2026-09-20 on PostgreSQL 18.6, holding the
method and changing only the container moved the median by 14 ms for `io_uring`
and 2.5 ms for `worker`, both far
short of 310.5 ms, so the gap is unlikely to be the container. But that 8kB
comparison was not itself run with the methods swapped, so treat it as a lead.

**`effective_io_concurrency`** went from 1 to 16 as a default in 18. It governs
how many storage operations one session tries to have in flight, which matters
most on high-latency storage and on devices with IOPS to spare. Set too high it
raises latency for everything else on the machine. It matters here because
queue depth is precisely what the AIO subsystem is trying to exploit: switching
`io_method` without checking this setting is changing the submission mechanism
for a queue you may not be filling.

**`io_workers`**, if you stay on the default method and it is not keeping up. It
reloads rather than restarts, and the table above shows it does not compete with
your parallel query budget, so it is the cheapest experiment on this page.

The first two are settable per session:

<!-- sql-check: pg 18+ -->
```sql
SET io_combine_limit = '128kB';  -- the 18 default, stated so the run is reproducible
SET effective_io_concurrency = 16;
EXPLAIN (ANALYZE, BUFFERS) SELECT count(*) FROM orders WHERE total > 100;
```

`BUFFERS` is redundant there on PostgreSQL 18:

> "Buffers information is automatically included when `ANALYZE` is used."
> ([PostgreSQL 18, EXPLAIN](https://www.postgresql.org/docs/18/sql-explain.html))

Confirmed on 2026-09-19 on PostgreSQL 18.6 in a stock `postgres:18.6` container:
a bare `EXPLAIN (ANALYZE)` printed the `Buffers:` line without being asked.

## When io_uring is worth it

The cost it removes is per-I/O overhead: context switches and the handoff to a
worker process. That overhead is a larger share of the total when there are many
small I/Os in flight against storage fast enough that the device is not the
bottleneck, on a machine busy enough for saved context switches to matter.

So the shape to test it on is fast local NVMe, real concurrency, and a workload
you have already established is read bound on the operations AIO covers:
sequential scans, bitmap heap scans and vacuum. Benchmark all three if all three
matter to you, because this page measured one of them.

And stage it: a canary or a replica first, in the same image and runtime class,
with a tested way back. `io_method` can only be set at server start, so getting
it wrong is an availability event rather than a bad query plan.

## Why does AI-generated code cause this?

Asked for a tuned `postgresql.conf` for PostgreSQL 18, a model will reasonably
include `io_method = io_uring`, because it is the newest and most specific option
and specificity reads as expertise. The file goes into a repository and reaches a
container that cannot start with it, weeks later, at a restart nobody planned as
a change.

The second pattern is the benchmark. Asked to prove a configuration change
helped, generated benchmarks restart PostgreSQL and rerun a query. That clears
the database's cache but not the operating system's, and it produces a confident
number about memory bandwidth.

The third is the one that cost the most time here: running both arms, seeing a
consistent gap, and stopping. Swapping the two arms and rerunning is what showed
the result to be an artefact.

## How do I stop it coming back?

**Treat `io_method` as a restart-risk change.** Anything in `postgresql.auto.conf`
that can stop the server from starting deserves the same care as a migration:
staged on a canary, verified in the same runtime, with a known-good path back.

**Check the build and the sandbox before you benchmark.** Two of the three gates
are yes-or-no and neither needs a stopwatch.

**Swap the arms before you believe a difference.** If the advantage follows the
container rather than the setting, you have measured the container.

**Prove your benchmark reaches the device, and do it before anything else.**
Identical block counts are a check that the arms match, not a check that
anything was read from storage: PostgreSQL's own statistics cannot distinguish a
physical read from a page cache hit, and neither can `pg_aios`. Ask the kernel
instead, per round, from the container's `/sys/fs/cgroup/io.stat` or the host's
`/proc/diskstats`. A container memory limit is not a substitute. It caps what
the container is charged for the page cache, not whether the page stays in host
RAM, and a benchmark can satisfy it while reading nothing at all.

**Record what you measured against.** Host, kernel, runtime, image, storage,
`shared_buffers`, every I/O setting on both arms, run count and ordering. A
single number with none of that attached is not evidence.

## How DBGorilla helps

The hardest part of this question is knowing whether you are I/O bound at all.
DBGorilla connects read-only and gives your AI coding agent metrics as time
series with rates and ratios computed across them, the workload by query
fingerprint including shared block reads against hits, and activity samples
showing what each session was waiting on rather than only that it was slow. That
is the evidence that decides whether an I/O setting is worth touching. It
surfaces and explains; it does not write to your database.
[Get started free →](https://app.dbgorilla.com/signup)

## Related

- [When to scale up vs optimize database queries](https://www.dbgorilla.com/learn/postgres/when-to-scale-up-vs-optimize-database-queries/)
- [Why are my queries spilling to disk? work_mem explained](https://www.dbgorilla.com/learn/postgres/why-are-my-queries-spilling-to-disk-work-mem/)
- [Why is Postgres 18 not using skip scan on my composite index?](https://www.dbgorilla.com/learn/postgres/why-is-postgres-18-not-using-skip-scan-on-my-composite-index/)