14 博采众长：内核分支与扩展生态

第 14 章博采众长：内核分支与扩展生态

PostgreSQL 的扩展生态很强，但“有这个扩展”不是架构理由，“能够安装”也不是生产结论。一个扩展进入数据库后，可能同时改变：

节点上的软件包、控制文件、SQL 脚本与动态库；
数据库里的类型、函数、操作符、访问方法和系统目录依赖；
主库、备库、备份恢复、逻辑订阅与大版本升级的前置条件；
安装、升级和删除所需的特权；
应用数据的可移植性、故障半径与退出成本。

因此本章不做“常用扩展清单”，而是建立一套可复用的治理方法：

先证明问题，再检查原生替代；先冻结版本与运行条件，再创建数据库对象；先演练升级、恢复和退出，再允许业务依赖。

第 15–17 章会分别深入检索、时空与分析/分布式能力。本章负责给它们提供同一把尺子，避免每遇到一个新扩展就重新发明评审标准。

本章完成后

你应当能够：

区分 PostgreSQL server、发行版/内核、OS 软件包、扩展支持文件与数据库扩展对象；
从 .control、版本 SQL、动态库与 pg_extension 解释一个扩展如何被发现、安装和拥有；
解释 superuser、trusted、relocatable、requires 与 shared_preload_libraries 各控制什么；
用 pg_available_extensions、pg_available_extension_versions、 pg_extension_update_paths() 与 pg_depend 取得原生证据；
不把“兼容 PostgreSQL”误解为扩展、目录、运维和故障语义都兼容；
用六个问题筛选扩展，而不是按热度、功能数量或安装便利度决策；
区分软件包版本与数据库对象版本，并设计受控的 ALTER EXTENSION UPDATE；
把备份恢复、物理备库、逻辑复制与 pg_upgrade 纳入扩展生命周期；
在 Pigsty 中区分仓库下载、节点安装、预加载配置和数据库启用；
解释包别名 pgvector 与 SQL 扩展名 vector 为什么不能混用；
识别节点漂移、control file 缺失、动态库缺失、未预加载与对象版本漂移；
写出包含问题、成功标准、供应链、权限、升级、恢复和退出的扩展 ADR；
对同一批候选给出“接受、限域试点、当前拒绝”三种有证据的结论。

三层状态，四个动作

扩展治理首先要拆开三层状态：

供应层
  repository/package/image
    └─ control + version SQL + shared library

进程层
  shared_preload_libraries / server restart / loadability
    └─ backend can load the module

数据库层
  pg_extension + member objects + extversion
    └─ this database can use the SQL interface

Pigsty 把典型流程组织成四个动作：

Download -> Install -> Configure -> Enable
仓库下载     节点装包    预加载/参数    CREATE EXTENSION

四步并非每个扩展都全部需要：

pg_trgm 有数据库对象，但不需要 shared preload；
vector 有数据库对象和动态库，本章版本也不需要 shared preload；
wal2json 是逻辑解码插件，装包后按插件名使用，并不要求 CREATE EXTENSION；
Citus、TimescaleDB 等扩展有额外预加载、拓扑或生命周期要求，必须查目标版本文档，不能类推。

反过来，完成最后一步也不能证明前面三层在所有节点一致。主库已经 CREATE EXTENSION，某台备库仍可能缺动态库；数据库目录显示 0.8.4， OS 仓库却已经换成另一构建。每层都需要独立证据。

贯穿实验：三个候选，三种结论

本章围绕 shop_ch14 评审三个候选：

问题	候选	结论	核心理由
单字段拼写容错	`pg_trgm`	accept	问题有界、contrib、受信任、GIN 可证、退出不锁定列类型
语义近邻检索	`vector`	pilot	能力成立，但模型、质量、资源、恢复与退出仍需真实语料证明
分布式分片	`citus`	reject now	尚无单节点上限证据、分片键合同和跨分片事务设计

“拒绝”不表示 Citus 有缺陷。Pigsty 当前扩展目录提供 Citus，说明平台有交付能力；本章仍拒绝它，是因为供应能力不能替代问题适配。

实验故意让权限差异可见：

pg36_owner (non-superuser, database owner)
  ├─ CREATE EXTENSION pg_trgm VERSION '1.3'  -> success
  │    trusted=true, extension owner=pg36_owner
  └─ CREATE EXTENSION vector VERSION '0.8.4' -> SQLSTATE 42501
       trusted=false, admin approval required

postgres/admin
  └─ CREATE EXTENSION vector -> success
       extension owner remains a superuser

pg36_app
  ├─ SELECT reviewed tables and use operators -> success
  └─ ALTER EXTENSION pg_trgm UPDATE            -> SQLSTATE 42501

随后由 pg36_owner 把 pg_trgm 从 1.3 更新到 1.6。更新前后：

trigram top ids = 1,5,2
vector top ids  = 1,2,5
trigram plan    = GIN bitmap index scan
vector plan     = HNSW index scan

这只证明固定五行夹具的机制与回归合同，不证明生产相关性、召回率或尾延迟。

实验资产

完整合同与入口：

正式本地证据在 Homebrew PostgreSQL 18.4 上采集。正文把平台映射核对到 Pigsty 4.4，但没有在 Pigsty L1 主机上运行，因此输出明确记录：

validation_path=direct-postgresql
pigsty_l1=not-run

这不是缺点掩饰，而是证据边界。读者在自己的 L1 上必须补采仓库、各节点包版本、预加载和数据库对象状态。

快速运行

沿用前章受控的 libpq service：

export PGSERVICEFILE=/path/to/pg_service.conf
export PGSERVICE=pg36-admin

PG36_EVIDENCE_DIR="$PWD/evidence/ch14" \
  ./static/labs/ch14/task.sh all

all 会：

验证数据库、角色、ch04-v1 模型和基础业务不变量；
对目标 schema 与同名扩展执行 marker/owner/version 碰撞保护；
以 owner 安装受信任的 pg_trgm 1.3；
证明 owner 安装未受信任的 vector 返回 42501；
由管理员安装 vector 0.8.4，建立 GIN 与 HNSW 夹具；
采集可用版本、control 属性、成员、ACL、索引和更新路径；
证明应用可查询但不能升级扩展；
记录升级前查询与强制索引计划；
把 pg_trgm 更新到 1.6，再次记录相同证据；
对 control、安装/更新 SQL 与动态库生成 SHA-256；
对比全库 schema dump 与 --schema=shop_ch14 选择性 dump；
把向量转为文本导出，形成试点退出材料；
验证错误 token、错误 target 和活跃 worker 下的 reset 拒绝；
不使用 CASCADE 精确复位，再从零完整重建和复验。

成功摘要：

status=ok
decision=pg_trgm:accept/vector:pilot/citus:reject
boundary=package+control+database-object
failure=42501-owner+42501-superuser
upgrade=pg_trgm:1.3->1.6-behavior-stable
index=gin+hnsw
dump=create-extension+selective-dependency-warning
exit=portable-text-export
pigsty_l1=not-run
release=1.2-proposal
release_candidate_checksum=6a4b74baec5f522eb098c868f1d4f1b441bf5b5f6708411588af0a8793f7f573

这个 proposal checksum 标识 ADR、版本、夹具和验收合同；运行时间、绝对安装路径以及文件系统 inode 不进入业务 golden。

安全边界
task.sh all 会删除并重建专用 shop_ch14，并删除带本章精确 marker 的 pg_trgm 与 vector。它只适合本书本地/开发夹具。生产安装和升级必须使用分阶段迁移、备库检查、恢复演练、观察窗口和独立回退，不运行 “先删后建”的教学入口。