pgsql.cc 上线：用 PostgreSQL 10–20 中文文档做好排障与升级

预计阅读时间：7 分钟

pgsql.cc 已上线 PostgreSQL 10 到 20 的 11 个大版本中文文档。它重新设计了官方站点的镜像界面，改进了全文搜索，并持续与上游内容同步，同时保持无广告。对日常维护数据库的工程师来说，它的价值不只是“把英文翻成中文”，而是让版本差异、配置参数和错误信息更容易被准确定位。

多版本文档为什么重要

PostgreSQL 文档与服务器版本必须对应。搜索某个参数、SQL 语法或系统视图时，如果误读了另一个大版本的页面，常见结果包括：

配置参数在当前版本中不存在，或者默认值已经变化；
SQL 示例使用了当前服务器尚未提供的语法；
系统目录或监控视图的字段发生变化；
升级指南中的兼容性说明被忽略；
运维人员把开发版本中的能力误认为生产版本已经可用。

因此，覆盖 10 到 20 的版本化中文文档，比单独维护一套“最新版说明”更适合排障和升级工作。尤其是在同时管理旧业务库、新集群和升级测试环境时，版本选择器本身就是文档体验的一部分。

需要注意：存在某个版本的文档页面，不等于该版本仍处于官方支持周期，也不等于它已经适合生产部署。评估升级或新建集群时，仍应单独确认版本的发布状态、生命周期、驱动兼容性和扩展支持情况。

搜索体验决定排障速度

数据库故障往往从一条错误信息开始。更实用的检索方式不是输入完整问题，而是组合以下信息：

PostgreSQL 大版本；
错误信息中稳定的英文片段；
SQL 关键字、配置参数或系统视图名称；
当前操作场景，例如 replication、VACUUM、JSON、index 或 authentication。

即使阅读中文文档，也建议保留英文错误文本和对象名称。PostgreSQL 的 SQL 关键字、参数名、函数名以及日志错误通常以英文为准，使用原文搜索更容易命中准确页面；中文说明则适合帮助理解上下文、限制条件和版本差异。

无广告也有实际意义：文档页通常会在生产故障期间频繁打开。减少干扰元素，可以降低误点风险，让页面更适合长期停留和交叉查阅。与上游同步则保证中文站点不是一次性快照，不过涉及高风险变更时，仍应核对当前页面对应的版本与更新时间。

可以这样实践：先识别版本，再查对应文档

在搜索之前，先从目标数据库采集准确版本和已安装扩展。下面的命令可直接运行；执行前把 DATABASE_URL 改成实际连接串，并确保本机已经安装 psql：

export DATABASE_URL='postgresql://app_user:password@127.0.0.1:5432/app_db'

psql -X "$DATABASE_URL" -v ON_ERROR_STOP=1 <<'SQL'
SELECT version();
SELECT current_setting('server_version') AS server_version,
       current_setting('server_version_num') AS server_version_num;

SELECT extname, extversion
FROM pg_extension
ORDER BY extname;
SQL

其中，server_version 适合人工阅读，server_version_num 更适合脚本判断。记录扩展版本也很重要，因为不少兼容性问题来自扩展，而不是 PostgreSQL 核心本身。

如果需要验证文档中的 SQL 行为，可以启动一个一次性的本地容器。把 PG_MAJOR 改成需要复现且镜像仓库中可用的大版本：

PG_MAJOR=16
CONTAINER=pg-doc-lab

 docker run --rm --name "$CONTAINER" \
  -e POSTGRES_PASSWORD=postgres \
  -p 55432:5432 \
  -d "postgres:${PG_MAJOR}"

until docker exec "$CONTAINER" pg_isready -U postgres >/dev/null 2>&1; do
  sleep 1
done

docker exec "$CONTAINER" psql -U postgres -v ON_ERROR_STOP=1 <<'SQL'
SELECT current_setting('server_version') AS server_version;
CREATE TABLE doc_test (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  payload jsonb NOT NULL
);
INSERT INTO doc_test (payload) VALUES ('{"status":"ok"}');
SELECT id, payload->>'status' AS status FROM doc_test;
SQL

docker stop "$CONTAINER"

这个实验环境适合验证语法、默认行为和最小复现，但不要把它当成完整的升级测试。生产兼容性还会受到操作系统、排序规则、扩展、连接池、驱动以及真实数据规模影响。

把中文文档纳入团队工作流

可以用下面这套流程减少“看错版本”的问题：

在故障单和变更单中固定记录 server_version_num；
分享文档时注明版本，而不是只复制页面标题；
优先搜索英文参数名、函数名和错误片段，再阅读中文解释；
对升级项目分别查阅源版本和目标版本文档；
将关键结论放进可执行的 SQL 或容器实验中验证；
对安全、备份恢复和重大版本升级，再核对上游发布说明与支持状态。

pgsql.cc 降低了中文用户阅读 PostgreSQL 文档的门槛，但真正可靠的使用方式仍然是“版本匹配、原词检索、实验验证”。把这三步固化到排障和升级流程中，中文文档就不只是参考资料，而会成为可重复的工程工具。

pgsql.cc 上线：用 PostgreSQL 10–20 中文文档做好排障与升级

多版本文档为什么重要

搜索体验决定排障速度

可以这样实践：先识别版本，再查对应文档

把中文文档纳入团队工作流

相关推荐

建议反馈