Skip to content

Should I switch Postgres 18 io_method to io_uring?

Last updated

View as Markdown

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.

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:

valuewhat 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.

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_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?

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 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 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:

profileresult
stock default profile, passed explicitlyFATAL: could not setup io_uring queue, container exited 1
same file plus those three namesstarted, 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.

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

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

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 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_workersio worker processes runningparallel workers launched
113 of 4 planned
443 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.

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_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:

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:

methodwaitsamplesshare
workerIO / AioIoCompletion478459.8%
workerno wait, backend running321640.2%
io_uringIO / AioIoUringExecution273934.2%
io_uringIO / AioIoUringSubmit241030.1%
io_uringno wait, backend running285135.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.

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 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:

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:

armroundsmedian
io_uring11 of 12: 5312 to 5394 ms5347 ms
worker12 of 12: 5320 to 5369 ms5336 ms
io_uring, round 210,775 msreported, 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:

arm6 roundsmedian
io_uring9003 to 10,771 ms10,455 ms
worker9780 to 10,844 ms10,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.

runcontainer, volumemethodroundsmedian
firstdbg-io-a, dbg-io-vaio_uring11 of 12: 5312 to 5394 ms5347 ms
firstdbg-io-b, dbg-io-vbworker5320 to 5369 ms5336 ms
after the swapdbg-io-a, dbg-io-vaworker5324 to 5370 ms5338.5 ms
after the swapdbg-io-b, dbg-io-vbio_uring5314 to 5354 ms5333 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.

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_limitread operationsbytes read
8kB323,6192,651,086,848
128kB20,2632,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:

method8kB128kB
io_uring6043, 6052, 6052, 6079 ms5322, 5341, 5343, 5363 ms
worker5707, 5711, 5772, 5774 ms5329, 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 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)

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.

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.

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.

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.