From 497eb813c0c41d870e3659c29876d42e750f666c Mon Sep 17 00:00:00 2001 From: spoondla Date: Mon, 12 Jan 2026 15:29:48 -0800 Subject: [PATCH] Document correct kernel requirements for io_uring While io_uring was introduced in Linux 5.1, PostgreSQL requires kernel version 5.6 or newer due to the io_uring operations it relies on. Earlier kernels may appear to support io_uring but can fail at runtime. Updated the internal AIO documentation and the sample configuration file to state the correct minimum kernel requirement. --- src/backend/storage/aio/README.md | 8 +++++++- src/backend/utils/misc/postgresql.conf.sample | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/backend/storage/aio/README.md b/src/backend/storage/aio/README.md index 72ae3b3737d..c40a6ce16cf 100644 --- a/src/backend/storage/aio/README.md +++ b/src/backend/storage/aio/README.md @@ -256,10 +256,16 @@ synchronous manner. #### io_uring -`io_method=io_uring` is available on Linux 5.1+. In contrast to worker mode it +`io_method=io_uring` is available on Linux 5.6+. In contrast to worker mode it dispatches all IO from within the process, lowering context switch rate / latency. +While io_uring was introduced in Linux kernel 5.1, the operations required by +PostgreSQL (IORING_OP_READ and IORING_OP_WRITE opcodes for non-vectored I/O) +are only available starting with Linux kernel 5.6. Attempting to use io_uring +on kernels between 5.1 and 5.5 will result in runtime errors (EINVAL) when +connections are established. + ### AIO Handles diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample index dc9e2255f8a..1648f4be207 100644 --- a/src/backend/utils/misc/postgresql.conf.sample +++ b/src/backend/utils/misc/postgresql.conf.sample @@ -204,7 +204,7 @@ # (change requires restart) #io_combine_limit = 128kB # usually 1-128 blocks (depends on OS) -#io_method = worker # worker, io_uring, sync +#io_method = worker # worker, io_uring (Linux 5.6+), sync # (change requires restart) #io_max_concurrency = -1 # Max number of IOs that one process # can execute simultaneously -- 2.39.5 (Apple Git-154)