From 4637c90abda1bbabdd9b3edb338ac386527331d4 Mon Sep 17 00:00:00 2001
From: Simon Massey <322608+simbo1905@users.noreply.github.com>
Date: Sun, 1 Nov 2026 09:08:56 +0000
Subject: [PATCH] docs/postgres: state libpq client floor (>=17) and
 client-vs-server distinction; name floor in spec pending message (#223)

---
 docs/RELEASE-LAYOUT-CN.md | 4 ++--
 docs/RELEASE-LAYOUT.md    | 4 ++--
 ext/postgres/README.md    | 5 +++++
 spec/postgres_spec.lua    | 2 +-
 4 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/docs/RELEASE-LAYOUT-CN.md b/docs/RELEASE-LAYOUT-CN.md
index 2520068..894676b 100644
--- a/docs/RELEASE-LAYOUT-CN.md
+++ b/docs/RELEASE-LAYOUT-CN.md
@@ -365,7 +365,7 @@ apt-get install -y libluajit-5.1-2 libuv1 zlib1g
 
 # 按你实际 require() 的驱动安装 - 不需要的可跳过
 apt-get install -y libcurl4          # lunet.httpc
-apt-get install -y libpq5            # lunet.postgres (requires libpq client >= 17)
+apt-get install -y libpq5            # lunet.postgres (requires libpq CLIENT >= 17; server can be pg16+)
 apt-get install -y libmariadb3       # lunet.mysql（在 Debian trixie 上提供 libmysqlclient.so）
 apt-get install -y libsqlite3-0      # lunet.sqlite3
 ```
@@ -379,7 +379,7 @@ PAXE（`liblunet_paxe`）与 crypto（`liblunet_crypto`）扩展各自静态链
 brew install luajit libuv
 
 # 按你实际使用的驱动安装
-brew install libpq          # lunet.postgres (requires libpq client >= 17)
+brew install libpq          # lunet.postgres (requires libpq CLIENT >= 17; server can be pg16+)
 brew install mysql-client   # lunet.mysql
 # sqlite3 使用系统库 - 无需额外安装
 ```
diff --git a/docs/RELEASE-LAYOUT.md b/docs/RELEASE-LAYOUT.md
index 833b8f3..baa80c0 100644
--- a/docs/RELEASE-LAYOUT.md
+++ b/docs/RELEASE-LAYOUT.md
@@ -392,7 +392,7 @@ apt-get install -y libluajit-5.1-2 libuv1 zlib1g
 
 # Per driver you actually use - skip the ones you don't require()
 apt-get install -y libcurl4          # lunet.httpc
-apt-get install -y libpq5            # lunet.postgres (requires libpq client >= 17)
+apt-get install -y libpq5            # lunet.postgres (requires libpq CLIENT >= 17; server can be pg16+)
 apt-get install -y libmariadb3       # lunet.mysql (provides libmysqlclient.so on Debian trixie)
 apt-get install -y libsqlite3-0      # lunet.sqlite3
 ```
@@ -406,7 +406,7 @@ The PAXE (`liblunet_paxe`) and crypto (`liblunet_crypto`) extensions each link l
 brew install luajit libuv
 
 # Per driver you actually use
-brew install libpq          # lunet.postgres (requires libpq client >= 17)
+brew install libpq          # lunet.postgres (requires libpq CLIENT >= 17; server can be pg16+)
 brew install mysql-client   # lunet.mysql
 # sqlite3 uses the system lib - no extra package needed
 ```
diff --git a/ext/postgres/README.md b/ext/postgres/README.md
index 2de9d8b..9d5a762 100644
--- a/ext/postgres/README.md
+++ b/ext/postgres/README.md
@@ -15,6 +15,11 @@ with an older client library fails at build time with a named error
 rather than silently producing an unusable module. Install libpq 17+ (see
 [RELEASE-LAYOUT.md](../docs/RELEASE-LAYOUT.md)).
 
+The floor is on the **libpq client library** at build/load time, not on the
+PostgreSQL server version: a libpq 17+ client talks to a pg16 server (for
+example Scaleway serverless Postgres) without issue — only the client
+library present when the module is built and loaded must be 17 or newer.
+
 | Function | Notes |
 |---|---|
 | `open(config)` | `host`, `port`, `user`, `password`, `database`, optional `connect_timeout`, `sslmode`, `pool_size` (default 1) |
diff --git a/spec/postgres_spec.lua b/spec/postgres_spec.lua
index e00dc4d..c6538f9 100644
--- a/spec/postgres_spec.lua
+++ b/spec/postgres_spec.lua
@@ -1,7 +1,7 @@
 describe("postgres module #native", function()
   local ok, pg = pcall(require, "lunet.postgres")
   if not ok then
-    pending("lunet.postgres not built (xmake build lunet-postgres)", function() end)
+    pending("lunet.postgres not built (xmake build lunet-postgres); if the build failed, check the libpq client library floor (libpq >= 17 required) — see ext/postgres/README.md", function() end)
     return
   end