0001-Document-correct-kernel-requirements-for-io_uring.patch

From 497eb813c0c41d870e3659c29876d42e750f666c Mon Sep 17 00:00:00 2001
From: spoondla <s_poondla@apple.com>
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)