一套标称为 PostgreSQL 14 的数据库抛出了一个 PostgreSQL 14 理论上不会产生的错误。这个故事的价值不在于“版本号看错了”这么简单，而在于提醒我们：生产环境里的数据库身份，不能只靠一个版本字符串判断。
当错误信息、客户端库、代理层、托管服务补丁、容器镜像和扩展混在一起时，“PostgreSQL 14”可能只是地图上的标签，不一定是现场的地形。
版本字符串只是入口，不是结论
排查数据库问题时，很多人第一步会问：你用的 PostgreSQL 几？这个问题必要，但不充分。
SELECT version(); 返回的是服务端自报信息。它通常可信，但它并不能单独解释所有现象。真实运行路径里还可能有这些变量：
- 连接是否打到了预期实例，而不是只读副本、旧环境或代理后的另一台机器。
- 云厂商是否打了补丁，导致错误文本、行为边界或构建信息和社区版略有差异。
- 客户端驱动、ORM、连接池是否改写了错误，或者把服务端错误和本地异常混在一起。
- SQL 是否经过代理、网关、审计插件、扩展或 FDW 转发。
- 容器镜像标签是否和实际二进制一致。
所以，“PostgreSQL 14 不能产生这个错误”不是终点，而是一个强信号：观测链路里至少有一个假设错了。
错误信息比版本号更像指纹
数据库错误通常包含几个层次：SQLSTATE、错误消息、上下文、服务端版本、客户端栈。版本号告诉你它自称是谁，错误细节告诉你它刚才做了什么。
可以这样实践：遇到“某版本不可能出现”的错误时，不要只截图错误文本。把服务端身份、连接路径和错误上下文一次性采集下来。
#!/usr/bin/env bash
set -euo pipefail
# 修改为你的连接串，例如：
# export DATABASE_URL='postgresql://app:secret@db.example.com:5432/appdb?sslmode=require'
: "${DATABASE_URL:?Please set DATABASE_URL}"
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 <<'SQL'
\echo '== server identity =='
SELECT
version() AS version_string,
current_setting('server_version') AS server_version,
current_setting('server_version_num') AS server_version_num,
current_setting('cluster_name', true) AS cluster_name,
inet_server_addr() AS server_addr,
inet_server_port() AS server_port;
\echo '== current connection =='
SELECT
current_database() AS database,
current_user AS user_name,
session_user AS session_user,
application_name,
client_addr,
backend_start
FROM pg_stat_activity
WHERE pid = pg_backend_pid();
\echo '== installed extensions =='
SELECT extname, extversion
FROM pg_extension
ORDER BY extname;
SQL
这段脚本不能证明“某个错误一定来自哪里”，但它能快速排除低级误判：连错库、连错端口、走了意外代理、扩展版本不一致、环境变量指向旧实例。
用 server_version_num 做判断，少解析字符串
在应用代码里，很多兼容逻辑会写成“如果 PostgreSQL 版本大于等于 14，就启用某功能”。这类判断不要解析 version() 的长字符串。它包含编译器、发行版、平台等信息，格式并不是给业务逻辑消费的。
可以这样实践：使用 server_version_num，它是整数形式。PostgreSQL 14 通常对应 140000 起步，补丁版本会体现在后续数字中。
#!/usr/bin/env python3
import os
import psycopg
# 安装依赖：python -m pip install 'psycopg[binary]'
# 运行前设置：export DATABASE_URL='postgresql://user:pass@localhost:5432/dbname'
def main() -> None:
dsn = os.environ["DATABASE_URL"]
with psycopg.connect(dsn) as conn:
with conn.cursor() as cur:
cur.execute("SHOW server_version_num")
version_num = int(cur.fetchone()[0])
cur.execute("SELECT version()")
version_text = cur.fetchone()[0]
print(f"server_version_num={version_num}")
print(f"version={version_text}")
if version_num >= 140000:
print("Treating server as PostgreSQL 14+ for feature gating.")
else:
print("Server is older than PostgreSQL 14; use compatibility path.")
if __name__ == "__main__":
main()
这个例子有一个重要边界：它只适合决定“是否启用某类版本相关功能”。如果你正在调查一个不该出现的错误，版本判断只是证据之一，还要结合实际 SQL、错误码、连接链路和服务端日志。
容器和 CI 里也要验证二进制
很多测试环境写着 postgres:14，但真正跑起来的东西可能被自定义镜像、缓存、挂载目录或初始化脚本影响。尤其在 CI 中，镜像标签、服务名和应用连接串经常发生漂移。
可以在 CI 里加入一个小的身份检查，让测试失败得更早：
name: postgres-identity-check
on:
pull_request:
push:
jobs:
check-db:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:14
env:
POSTGRES_PASSWORD: postgres
POSTGRES_DB: app_test
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 5s
--health-timeout 5s
--health-retries 10
steps:
- name: Install PostgreSQL client
run: sudo apt-get update && sudo apt-get install -y postgresql-client
- name: Verify server version
env:
PGPASSWORD: postgres
run: |
psql -h localhost -U postgres -d app_test -v ON_ERROR_STOP=1 <<'SQL'
SELECT version();
SELECT current_setting('server_version_num')::int >= 140000 AS is_pg14_or_newer;
SQL
这不是为了迷信 CI，而是为了把“我以为跑的是 14”变成可审计的事实。
采纳建议：把假设变成可观察数据
这类问题最容易浪费时间的地方，是团队围着一个版本号争论。更稳的做法是建立一套排查清单：
- 记录完整错误：SQLSTATE、错误消息、上下文、触发 SQL、客户端栈。
- 同时采集
version()和server_version_num。 - 确认连接目标：主机、端口、数据库名、当前用户、
inet_server_addr()。 - 检查代理、连接池、只读副本、迁移脚本和扩展。
- 在 CI 和启动检查中验证数据库身份，不把镜像标签当作事实。
版本号仍然有用，但它只是一个坐标。真正的现场真相来自多点观测：服务端实际返回什么、客户端实际连到哪里、错误实际从哪一层冒出来。遇到“这个版本不可能报这个错”时，最好的反应不是立刻否定现象，而是把每一层假设拆开验证。