PG Catalog Atlas

PostgreSQL 系统目录演化图谱。基于 Hugo 与 Oink 1.0.0，将 PostgreSQL 9.0–9.6、10–19 的系统目录、系统视图、统计和进度视图整理成可检索、可对比、可下载的数据集。

快照基准：2026-09-08。PostgreSQL 18 为当前稳定大版本，19 为预览版；预览结构仍可能变化。

当前数据包含 157 个关系、2,032 份关系快照、19,171 条字段记录，记录 335 条结构变化及 732 条全部相邻版本变化。官方来源归档共 2,631 个文件，其中 1,567 份 HTML。相比原项目，额外收录 14 个真实存在的统计视图变体。

原项目研究

Richard Yen 的 PG Catalog Almanac 开源，采用 MIT 许可证。GitHub 不仅有 React/Vite 界面，还有 scripts/extract-catalog-data.mjs 提取器和 src/data/catalog.json 原始数据。

原网站 是单页应用：HTML 是应用外壳，所有版本的数据嵌在部署后的 JavaScript 文件里，并非只能从浏览器渲染结果反向抓取。#/r/pg_class 和 #/v/16 是客户端路由，不是独立的服务器 HTML 文件。保留 HTML、JS、CSS 和数据即可保存全部原始页面所需的内容。

原始项目源码、原站部署资源、原始 JSON 与来源记录保存在 sources/almanac/。详细证据见 上游研究。

启动与构建

需要 Hugo Extended 0.160.1+ 和 Python 3.10+。主题已按 v1.0.0 固定在 themes/oink/，正常构建不需要下载主题，也不需要 Node/npm 或数据库服务。

make serve                    # http://localhost:1317/
make build                    # 生成 public/ 静态网站
make check                    # 严格构建、数据验证、链接与静态页面完整性检查

网页和数据都已生成。运行数据校验或重建数据时需要 Python 解析依赖；普通网站构建只使用 Python 标准库：

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
make data PYTHON=.venv/bin/python      # 仅从归档离线重建
make refresh PYTHON=.venv/bin/python   # 补取缺少的官方源文件并重建
make archive                         # 保存上游网站与源码
make reconcile                       # 对比本项目与上游重叠版本的数据

验证结果见 验收记录。完整离线重建后，217 个数据导出文件逐字节一致，记录在 data/reproducibility.json。

refresh 复用已缓存的历史文件。它不代表静默替换快照或自动加入未来版本；更新版本范围与快照应修改采集配置并重新审计。

部署时设置实际站点地址，然后将 public/ 放到任意静态 Web 服务器。例如：

hugo --baseURL https://your-domain.example/ --minify

完整覆盖与运行时校准

覆盖页面按版本展示目录表、视图、字段数量及原始实测 JSON。static/data/calibration.json 记录 28 条校正：2 处漏列、3 处字段名错误、19 处类型错误和 4 处引用错误；类型别名另外规范化。static/data/source-inventory.json 给出独立源码清单。

make check 离线运行两套独立校验：源码关系清单，以及运行时字段清单、类型、顺序、可空性和实际相邻类型变更。普通构建不启动数据库。运行时探测 SQL、构建参数、原始结果与校验信息保存在 scripts/runtime_schema.sql 和 sources/runtime/；只有重新采集实例时才需要 Docker 和 PostgreSQL 构建环境。

数据与目录

路径	用途
sources/almanac/	原站完整资源、源码、原始 JSON 与下载依据
sources/postgresql/	各版本官方 HTML、用于补全的 PostgreSQL 源码及 SHA-256 清单
static/data/catalog.json	主数据集：关系、各版本字段、类型、说明、来源及相邻版本变化
static/data/	网站直接提供的结构化数据与导出文件
data/catalog.json	Hugo 构建使用的数据镜像，由生成脚本维护
content/catalog/	每个关系的静态页面入口，由生成脚本维护
layouts/、assets/	图谱、字段矩阵、版本对比的组件与样式
themes/oink/	保留原始许可证的 Oink 1.0.0 主题
scripts/build_catalog.py	缓存采集、解析、规范化、差异计算和导出
scripts/generate_content.py	数据到 Hugo 页面生成
scripts/audit_source_inventory.py	独立核对完整发布源码中的所有表与视图
scripts/audit_column_types.py	独立核对全部 17 个实例的完整字段与类型变化
sources/runtime/	原始运行时快照、构建参数、SQL 结果与校验信息
scripts/test_catalog.py	数据完整性与历史变更回归检查
scripts/check_site.py	全站内部链接、资源与静态关系页面检查
scripts/reconcile_almanac.py	与上游独立数据集交叉核对

如何理解“变化”

这里记录的是所覆盖大版本快照之间的关系与字段结构差异。字段新增、移除、类型变化与说明文字变化分开记录；不将字段改名自动推断为语义上的同一字段。9.0 中已经存在的对象是基线，不能据此推断它最初在 9.0 引入。

范围覆盖所有核心 pg_catalog 普通目录表与视图，已对完整源码清单和全部 17 个准确发布版本的新建实例进行核对。共 19,171 条字段记录，另外保留 5,934 条通用系统列记录；历史文档中的漏列、类型错误与拼写错误均有单独校准记录。它不枚举系统目录中的每一条数据记录、所有函数与索引，也不声称覆盖每一个小版本或 Git 提交的内部变化。

旧文档存在特殊情况：9.0/9.1 统计视图缺少完整字段表、早期目录可能省略隐式 oid、某些文档用 stakindN 表示一组实际字段。采集器保留原文和补全依据，避免将文档排版变化或省略制造成数据库结构变更。详见 数据方法。

官方页面按采集时保存的内容重建；原 Almanac 的数据来自它记录的发布标签。两者的重叠版本差异保存在 docs/upstream-reconciliation.json，用于复核，不能把“与上游不同”直接等同于错误。

来源与许可

感谢 Richard Yen 的 PG Catalog Almanac、PostgreSQL 官方文档和 Oink。各上游许可证和作者署名均保留，详见 NOTICE。