Should I switch Postgres 18 io_method to io_uring?
Quick answer: Stay on
workerunless 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 fromio_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 inpostgres:18.6containers 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?
Section titled “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
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:
| value | what the PostgreSQL 18 resource configuration documentation 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
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
Section titled “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?
Section titled “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:
SELECT setting LIKE '%--with-liburing%' AS has_liburingFROM 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?
Section titled “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 permittedHINT: 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
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:
{ "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?
Section titled “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
Section titled “What is set by default”Measured on 2026-09-19 on PostgreSQL 18.6 in a stock postgres:18.6 container:
SELECT name, setting, boot_val, contextFROM pg_settingsWHERE 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 userio_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
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?
Section titled “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:
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
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:
SELECT pid, state, operation, off, length, target, target_descFROM pg_aiosLIMIT 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:
SELECT type, name, descriptionFROM pg_wait_eventsWHERE 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 queueAioUringCompletion 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?
Section titled “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:
CREATE TABLE bench ASSELECT g AS id, repeat('x', 200) AS padFROM 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:
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
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
Section titled “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,
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
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:
SET io_combine_limit = '128kB'; -- the 18 default, stated so the run is reproducibleSET 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
ANALYZEis used.” (PostgreSQL 18, EXPLAIN)
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
Section titled “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?
Section titled “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?
Section titled “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.
What is io_method in PostgreSQL 18?
It selects how PostgreSQL executes asynchronous-eligible I/O, which in 18 means queued reads for sequential scans, bitmap heap scans and vacuum. It does not route every read and write in the server. The default is worker. io_uring submits through the Linux kernel interface of that name and requires a build with --with-liburing. sync executes the same asynchronous-eligible I/O synchronously. It is a postmaster setting, so changing it requires a restart.
Does io_uring make PostgreSQL faster?
It can, and it did not here. Measured on 2026-09-20 on PostgreSQL 18.6 in postgres:18.6 containers on one host running Linux 6.17.0-1022-azure with 8 vCPU and Docker 29.1.3, on a 2528 MB table, with the host page cache evicted before every scan and the kernel's own byte counter confirming each round pulled 2528 MB off the device: twelve interleaved rounds gave io_uring a median of 5347 ms against worker at 5336 ms, ranges 5312 to 5394 and 5320 to 5369. Swapping the two methods onto the opposite containers on 2026-09-20, on PostgreSQL 18.6 on the same protocol, gave worker 5338.5 ms and io_uring 5333 ms. Both gaps are smaller than the 82 ms that one arm covers on 2026-09-20 on PostgreSQL 18.6 between its own fastest and slowest round, so there is nothing here to attribute to either the method or the container. Run without that eviction, which is the protocol that measures host RAM and reports it as disk, the same three arms gave io_uring a median of 3209 ms against worker at 2416 ms, so io_uring was 793 ms slower, which is 33 percent of that 2416 ms, and the gap was the cache and not the method.
Why does my server fail to start with io_uring?
Docker's default seccomp profile allows 426 distinct syscalls and none of them are io_uring syscalls, so queue setup returns EPERM. Measured on 2026-09-19 on PostgreSQL 18.6 in a postgres:18.6 container under Docker 29.1.3 on Linux 6.17.0-1022-azure, startup failed with 'FATAL: could not setup io_uring queue: Operation not permitted' and the container exited. Adding io_uring_setup, io_uring_enter and io_uring_register to a copy of that profile was the only change needed to make it start.
How do I tell which io_method is running?
SHOW io_method is the authoritative answer, because it reports the configured setting. The process list corroborates it: with io_method=worker there are io worker processes and with io_uring there are no io worker processes. Measured on 2026-09-19 on PostgreSQL 18.6 in postgres:18.6 containers on Linux 6.17.0-1022-azure, 3 and 0. Note that SHOW io_workers still reports 3 under io_uring, where the documentation says the parameter has no effect.
What should I change instead?
Check io_combine_limit before you touch io_method. Its 128kB default is where the visible sequential read improvement in 18 comes from. Measured on 2026-09-20 on PostgreSQL 18.6, Linux 6.17.0-1022-azure, 8 vCPU, in postgres:18.6 containers on a 2528 MB table with the host page cache evicted before every scan: under io_method=worker the scan took 5329 to 5372 ms at the 128kB default against 5707 to 5774 ms at 8kB, and under io_method=io_uring 5322 to 5363 ms against 6043 to 6079 ms. The default also turned 323,619 read operations into 20,263 for the same 2,651,086,848 bytes. The 128kB default won all eight pairs, on both methods, saving 11.7 percent of the 8kB median on io_uring and 6.9 percent on worker, which is a larger and far more repeatable effect than any difference between io_method values here. Then look at effective_io_concurrency, which sets the queue depth the AIO subsystem is there to exploit.