附录 F：术语与技术边界表

同一个词在 PostgreSQL、Pigsty、云平台和 Kubernetes 中可能指不同对象。本附录固定 全书用语；命令执行前仍要解析 exact identity，不能只靠名词。

F.1 PostgreSQL、Pigsty、Patroni、PgBouncer 与 HAProxy 术语

PostgreSQL

全书核心知识对象。原生证据来自 SQL/catalog/stats、server log、control/WAL/backup metadata 和 filesystem/OS。平台结论最终要能回到这些语义验证。

Pigsty

PostgreSQL 数据库服务的参考实现/发行与管理平台。它把多个独立组件通过配置、playbook、 service 和监控组合起来。pig 是相关 CLI/package/operations 工具，其版本号与 Pigsty release 不同，例如正式实验观察到 pig 1.5.1 与 Pigsty v4.4.0。

Patroni 与 DCS

Patroni 不“复制数据库”；PostgreSQL streaming replication 复制 WAL。Patroni 根据 DCS leader state、成员健康和配置协调 promotion/demotion。DCS 可用不证明 PostgreSQL 数据最新，PostgreSQL 可写也不证明它仍拥有集群 authority。

PgBouncer

三种 pool mode（session/transaction/statement）改变 server connection 的租用边界。 transaction pooling 下，不应假定跨 transaction 保留 temp table、session GUC、 prepared statement 或 advisory-lock 语义；实际能力还受 PgBouncer/driver 版本与配置 影响。

HAProxy

Pigsty service port 用 health endpoint/selector 将流量送到合适 instance/PgBouncer。 client 连接 HAProxy 的 address 与 PostgreSQL inet_server_addr() 返回的 backend address 不同，是正常的两层 identity。

F.2 实例、database cluster、Pigsty cluster 与服务端点

对象层级

host/node
  -> PostgreSQL instance/server (one postmaster + PGDATA + port)
     -> PostgreSQL database cluster (all databases in that PGDATA)
        -> database
           -> schema
              -> relation/function/type/extension objects

PostgreSQL 官方术语中的 database cluster 是一个 server/PGDATA 管理的 database 集合，不等于三节点 HA cluster。

Pigsty pg_cluster

Pigsty 把共享 pg_cluster 名称的 PostgreSQL instances 组织为一个管理/HA 单元：

pg-test
  pg-test-1 primary
  pg-test-2 replica
  pg-test-3 replica/offline

每个 instance 有自己的 PGDATA，是同一 PostgreSQL system lineage 的物理副本。 pg-meta 与 pg-test 名称相近也可能拥有不同 system identifier，不能互相 restore/ rewind。

容易混淆的 identity

service endpoint

服务端点表达能力语义，而不是机器：

primary service  -> current writable authority, usually via pool
replica service  -> selected read-only members, may lag
default service  -> current primary direct PostgreSQL
offline service  -> offline/analytics-selected member

具体端口与 selector 以当前 Pigsty config 为准。DNS、VIP、HAProxy node 和 backend 是 不同层；连接串只显示入口，SQL identity 显示实际 backend。

system identifier 与 timeline

system identifier
  PostgreSQL lineage identity；不同初始化通常不同

timeline
  WAL history 分支；promotion 通常产生新 timeline

LSN
  某条 timeline/WAL stream 内的位置语义

同 LSN 字符串在不同 system/timeline 不能直接比较。failover、rewind、PITR、restore 必须同时证明 source direction、system identifier 和 timeline history。

F.3 [PG]、[平台]、[Pigsty] 能力映射

这些标签用于作者的能力分析，不出现在顶层导航标题中：

PostgreSQL native capability
  引擎/SQL/catalog/tool 直接提供并可原生验证

generic platform responsibility
  任何生产数据库服务都必须承担，但不一定由 PostgreSQL 自己完成

Pigsty mapping
  Pigsty 对平台责任的具体组件、inventory、playbook、service 或 dashboard 实现

示例

使用规则

1. 先解释 PostgreSQL 语义；
2. 再说明生产服务缺少什么组合责任；
3. 给出 Pigsty reference implementation；
4. 回到 SQL、config 或 component state 复核；
5. 标明替换平台时必须保留的责任，而不是复制 Pigsty 命令。

例如“backup green”不是 PostgreSQL 原生结论；它组合 pgBackRest、repository、monitor、 restore drill 与业务 manifest。迁移到 RDS/Operator 后工具不同，责任仍在。

F.4 托管 RDS、自建 Patroni 与 Operator 的职责对照

三种交付模型

“托管”转移部分实施责任，不转移业务正确性、权限配置、查询/模式、RPO/RTO 接受、 external side effect 与 vendor failure 的验证责任。

自建 Patroni/Pigsty

优点：

完整 PostgreSQL/extension/OS 控制
可审查组件与数据路径
统一声明式平台和可观测

代价：

DCS/fencing/failure domain
package/OS/security lifecycle
backup repository and restore
on-call and incident authority

Pigsty 提供强 reference baseline，但 production topology、secrets、capacity、DR 与业务 合同仍由采用者验收。

Operator

Operator 用 Kubernetes reconciliation 管理 PostgreSQL lifecycle；它不等于：

Kubernetes automatically provides database consistency
pod restart equals failover safety
PVC equals backup
Service equals correct writer authority

需要理解 operator CRD、leader/lease、pod/PVC/node/zone failure domain、backup integration、disruption/upgrade 和 platform control-plane dependency。

选择问题

required PostgreSQL/extension control
team operating skill and on-call model
failure domains and regulatory/data residency
RPO/RTO and restore evidence
version/upgrade cadence
cost and lock-in
observability/export/access
exit and migration path

不要只比较“有没有 HA/backup”勾选项；比较故障模型、验证接口、责任边界和失败时的 authority。

返回附录目录 · 对象与证据速查 · 第 1 章全局地图 · 查看全书目录