附录与速查

附录用于快速定位版本、证据、症状、分区、实验安全和术语边界。它们不替代正文中的 机制与实验：遇到事故先按附录 C 找到首个安全动作，再进入目标章节完成证据分类。

附录 A：版本矩阵与差异注记

冻结 PostgreSQL 18.6、Pigsty v4.5.0、pig 1.5.1 与正式 L1/L2/L3 基线；说明哪些 结论必须按版本重验，以及勘误如何保留历史适用范围。

附录 B：对象、视图、命令与证据速查

按连接、对象、事务、锁、计划、复制、WAL、backup、vacuum 和容量定位首选证据； 每个动作同时标注风险、前置与 after 验收。

附录 C：症状与首个安全动作索引

从误操作、主库/DCS、复制、连接/锁、资源、XID、WAL 和完整性症状路由到 ch31～ch35； 明确第一步和绝不能做的捷径。

附录 D：分区能力索引

串联 ch04 决策、ch07 裁剪、ch11 在线迁移、ch16 时间语义与 ch28 生命周期。

附录 E：实验拓扑、风险与复位手册

定义 L1/L2/L3 规格，区分 R0–R3 风险，解释 reset:sql、reset:cluster、 reset:host 以及 snapshot/checksum/evidence 合同。

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

区分 PostgreSQL、Pigsty、Patroni、DCS、PgBouncer、HAProxy、实例、两种 cluster 与 service endpoint，并对照 RDS、自建和 Operator 的责任。

返回全书导读 · 查看全书目录 · 查看索引中心

附录 A：版本矩阵与差异注记

本附录是全书的版本控制面。正文中的原理尽量保持跨小版本稳定，但命令、默认值、组件组合和界面必须绑定实际版本。读者复现实验时，先记录事实，再判断差异是否影响结论。

A.1 PostgreSQL、Pigsty、OS、Patroni、PgBouncer、备份工具与扩展版本

本书复现基线：

L2 的三台 pg-test VM 在正式 run 中只有 1 vCPU、约 1.9 GiB RAM，是明确记录的 sandbox exception；它证明实验在该下限跑通，不构成生产 sizing。精确资源、网络和 限制见附录 E与 ch19/requirements.json。

Patroni、PgBouncer、HAProxy、pgBackRest 与扩展的小版本可能随操作系统仓库和离线包变化，因此不在正文中假定一个虚假的全平台统一值。进入实验节点后采样：

{
  printf 'captured_at=%s\n' "$(date -Is)"
  uname -a
  cat /etc/os-release
  postgres --version
  psql --version
  patronictl version
  pgbouncer --version
  haproxy -v
  pgbackrest version
} > component-versions.txt 2>&1

命令不存在或需要不同 PATH 时，保留失败输出并从软件包管理器补充，不得把“未采集”写成“未安装”。服务端 PostgreSQL 版本还要从连接内部复核：

SELECT
    current_setting('server_version') AS server_version,
    current_setting('server_version_num') AS server_version_num,
    version() AS build;

扩展分为“操作系统已提供”和“当前数据库已安装”两层。后者使用：

SELECT extname, extversion
FROM pg_catalog.pg_extension
ORDER BY extname;

不要用 pg_available_extensions 代替已安装清单，也不要假设一个数据库安装的扩展会自动出现在同实例的其他数据库中。

A.2 强版本相关行为：并发 DDL、预备语句、排序规则、升级与恢复

下列主题不得只写“PostgreSQL 支持”：

强版本相关实验在正文中同时给出“本书基线的已验证路径”和“迁移到其他版本时要重新验证的观察点”。不能验证的行为明确标为未决，不用相近版本输出冒充。

A.3 版本增量通过记录与勘误链接

每次升级复现基线都执行一次版本增量验证：

1. 创建全新的 L1，记录安装制品校验值与全部版本；
2. 从 ch01 开始运行 setup、exercise、verify 与 reset；
3. 对比系统目录、命令输出、默认值和服务路由；
4. 将差异分为“输出变化”“行为变化”“安全边界变化”“实验失效”；
5. 修正文稿与脚本，并记录最小受影响版本范围；
6. 方法、架构、事故三类代表性章节通过后，再推进全书回归。

勘误记录至少包含：

版本更新不覆盖历史事实。若旧版行为在当时确实成立，应保留适用范围并补充新行为；只有事实本身错误时才作为勘误修正。

附录 B：对象、视图、命令与证据速查

本附录用于事故前后的快速定位，不替代正文中的机制、权限与风险判断。所有视图和命令 按 PostgreSQL 18 / Pigsty v4.5 基线列出；跨版本先查附录 A。

B.1 连接、角色、对象、事务、锁和计划

身份与对象

最小 identity：

SELECT
    current_database(),
    current_user,
    session_user,
    inet_server_addr(),
    inet_server_port(),
    pg_is_in_recovery(),
    current_setting('server_version_num');

psql：

元命令适合交互探索；可审计脚本应同时保存等价 catalog query、目标 identity 和版本。

会话、事务与锁

等待链骨架：

SELECT
    a.pid,
    a.application_name,
    a.state,
    a.wait_event_type,
    a.wait_event,
    a.xact_start,
    pg_catalog.pg_blocking_pids(a.pid) AS blocking_pids
FROM pg_catalog.pg_stat_activity AS a
WHERE a.datname = current_database()
ORDER BY a.xact_start NULLS LAST, a.pid;

query text 可能含敏感数据、被截断或因权限不可见。取消/终止 backend 是有副作用动作， 先绑定 exact PID + backend start + application/user/database + expected/stop。

计划与语句

ANALYZE 选项会真的执行语句；对 INSERT/UPDATE/DELETE/MERGE 或 volatile function， 先在可回滚/隔离环境设计，不要对生产写语句直接照抄。正文： ch07、ch08、 ch09、ch10。

B.2 复制、备份、vacuum、WAL 与容量

复制、权威与 WAL

不要手工删除 pg_wal。WAL 撑盘先判 archive、slot、replica、backup/restore owner；见 ch34 与附录 C。

backup 与 restore

“最近 backup success”不等于能在目标 RTO 内恢复，也不证明正确 target。恢复必须在隔离 candidate 验证；见 ch21 与 ch32。

vacuum、freeze 与膨胀

膨胀不是单一准确 counter。stats 是估算且可 reset；结合 page/sample/extension 工具时 记录版本、锁和开销。见 ch28。

容量与配置

work arrival / concurrency / queue
CPU run and saturation
memory budget and OOM/swap
I/O latency, throughput and queue
connections and per-operation memory
WAL/archive/replication retention
XID/multixact age
data/index/temp/log/backup storage

PostgreSQL：

同时采样 OS vmstat、iostat、pidstat/cgroup/host metrics。数据库 counter 不能解释 所有 kernel/device 行为。见 ch25～ch27。

B.3 每项命令的风险等级、适用范围和验证方式

先填 action card

target:
  environment:
  cluster/system:
  instance/database/object/session:
risk: R0 | R1 | R2 | R3
authority:
preconditions:
expected:
stop:
rollback_or_recovery:
before_evidence:
after_evidence:

风险由目标与后果决定，不由命令长短决定。同一 PITR 机制在一次性隔离 candidate 上可为 R2，切换生产 authority 或覆盖真实目标时应升为 R3。SELECT 可调用 volatile/security definer function；EXPLAIN ANALYZE 可执行写入；VACUUM FULL、REINDEX、DDL 和 playbook 可能持锁、重写、重启或改变路由。

常见动作速查

pg_resetwal、zero_damaged_pages、ignore_checksum_failure、手改 relation/WAL 不属于 普通速查动作；仅在证据 clone、明确损失和专业升级下考虑，见 ch35。

验证模板

before
  exact identity + objective + independent baseline

action
  command/source hash + parameters + exit/stdout/stderr + authority

after
  expected observation + no-regression + business invariant

restore
  temporary artifacts removed or retained by policy

boundary
  what this evidence does not prove

退出码 0、service active 和 dashboard green 都只能证明局部命题。

返回附录目录 · 症状索引 · 实验风险与复位 · 查看全书目录

附录 C：症状与首个安全动作索引

这是“先别把事故变糟”的路由表，不是自动诊断器。任何症状先确认 environment、 cluster/system identity、用户影响、数据风险和变化速度；证据缺失或冲突时进入 ch31 的 STOP_AND_ESCALATE，不要强行匹配一行。

C.1 误删误改、主节点故障、DCS 故障、复制停滞

误操作的最小记录

who/role/application
exact database/schema/object
transaction identity and commit status
first known bad / last known good
external dispatch and caches
backup + WAL coverage
post-target legitimate writes

应用 timeout 不能证明 transaction 回滚；先用 request/idempotency token 对账。

“主库故障”的分层

user/client
  -> DNS/VIP/HAProxy
  -> PgBouncer
  -> PostgreSQL listener/session
  -> Patroni/DCS authority
  -> storage/host/network

代理错误不应触发数据库 promotion；进程停止也不等于硬件已围栏。每层用独立证据， 接受新 writer 前证明旧 writer 不能继续拥有 authority。

C.2 连接耗尽、锁等待、CPU、内存、I/O 与 OOM

flow pressure 的首要目标

reduce arrival
reduce concurrency
reduce per-item cost
protect critical lane

按 service/role/application_name/query class 精确限流、降级或取消，并定义 expected、 stop、rollback。客户端 retry 没有 backoff/jitter/idempotency 时，会把短故障放大为 持续过载。

retention pressure 不走限流捷径

WAL、XID 或磁盘满可能由仍被声明为“需要”的历史边界造成。取消慢 SQL 不一定推进 slot restart_lsn 或旧 xmin。先查 owner、恢复/复制语义，再清 exact owned consumer。

详见 ch22 连接预算、 ch25 可观测 和 ch34 资源事故。

C.3 XID 回卷：先查 backend_xmin、复制槽 xmin、pg_prepared_xacts

首个目标：找谁钉住 horizon

SELECT
    datname,
    age(datfrozenxid) AS xid_age
FROM pg_catalog.pg_database
ORDER BY xid_age DESC;

SELECT
    pid,
    datname,
    usename,
    application_name,
    backend_xmin,
    xact_start,
    state,
    wait_event_type,
    wait_event
FROM pg_catalog.pg_stat_activity
WHERE backend_xmin IS NOT NULL
ORDER BY xact_start NULLS LAST;

SELECT
    slot_name,
    slot_type,
    active,
    xmin,
    catalog_xmin,
    restart_lsn
FROM pg_catalog.pg_replication_slots;

SELECT *
FROM pg_catalog.pg_prepared_xacts
ORDER BY prepared;

再查：

autovacuum/freeze progress and logs
table relfrozenxid/relminmxid age
long-running idle-in-transaction
logical decoder/subscriber owner
prepared transaction business owner
disk and WAL headroom

动作边界

• 先阻止新的长事务/无界读取，保护 maintenance lane；
• exact backend 取消/终止需要业务 owner 和 commit/rollback 影响判断；
• slot 可能代表 DR、CDC 或恢复承诺，不能只因 inactive 删除；
• prepared transaction 要按业务协议 commit/rollback，不能猜；
• 提高 freeze 参数或跑更激进 vacuum 前确认 I/O、WAL、lock 与时间余量；
• 接近 wraparound 时升级 severity 与 authority，不在压力下尝试不熟悉的 catalog 修改。

路由：ch28 VACUUM、冻结与膨胀； 资源止血见 ch34.6。

C.4 WAL 撑盘：先查归档、复制槽和备份保留者，绝不手工删除 pg_wal

先建立 conservation picture

generation rate
  pg_stat_wal + workload/checkpoint

archive
  pg_stat_archiver + archive logs + repository

physical/logical consumers
  pg_stat_replication + pg_replication_slots + subscriptions

restore/backup
  pgBackRest process, spool, lock and repository

filesystem
  PGDATA/pg_wal mount, free bytes/inodes, I/O errors

常见分类：

首个安全动作

1. 停止非关键的大写入、bulk/DDL 与 retry 放大；
2. 保留管理连接和当前 slot/archive/replication evidence；
3. 估算 time-to-full，而不是只报百分比；
4. 确认能否安全扩容/迁移 filesystem；
5. 修复 exact owned consumer，或在审批后清理；
6. 验证 archive continuity、replica/slot 和 backup。

绝不手工删除 pg_wal、伪造 archive success 或随意 pg_resetwal。这些动作会破坏 crash recovery、replication 或 PITR，且可能把可恢复事故变成不可恢复损坏。

C.5 checksum、索引、collation 与逻辑不一致

不能互相替代

checksum clean
  != index order correct
  != business data correct

amcheck pass
  != heap/page/storage safe

service starts
  != recovered data trusted

抢救先保存 original evidence，再从同一 snapshot 分叉 working clone。危险恢复参数仅在 clone、明确接受损失和专业升级下使用。详见 ch35 数据抢救与取证。

C.6 每一行同时标明目标章节、首个安全动作和禁止动作

总路由

首个动作卡

symptom:
target_identity:
user_impact:
data_and_recovery_risk:
changing_now:
first_safe_action:
evidence_before:
expected:
stop:
rollback:
owner_and_authority:
route_if_supported:
route_if_unknown: STOP_AND_ESCALATE

若没有权限执行首个动作，正确动作是升级 owner 并继续只读取证，而不是扩大权限范围。

返回附录目录 · 对象与证据速查 · 实验风险与复位 · 查看全书目录

附录 D：分区能力索引

分区不是一个孤立功能：是否该用、查询能否裁剪、如何在线迁移、时间边界怎样表达、 旧分区如何冻结/退役，分布在五个章节。本附录把它们串成一条生命周期。

D.1 ch04：分区决策门

ch04.6 先问：

dominant lifecycle boundary?
queries usually constrain the same key?
retention/archive needs cheap detach/drop?
maintenance can benefit from smaller independent relations?
number and creation rate of partitions remain bounded?

不要因为“表会变大”自动分区。分区会增加：

• parent/child catalog、DDL、statistics 与 plan 开销；
• partition creation/retention automation；
• constraint/unique/FK 设计限制；
• prepared/generic plan 与参数裁剪不确定性；
• cross-partition query/index/maintenance 复杂度；
• migration、default partition 和 late-arriving data 处理。

key 选择

使用 [start, end) 边界，显式时区与 catch-all/拒绝策略。parent-level PRIMARY KEY / UNIQUE 必须满足当前 PostgreSQL 对 partition key 的要求；不能假设多个本地索引自动 提供任意全局唯一性。

决策交付物

decision: partition | do-not-partition | revisit
key_and_method:
business_and_retention_boundary:
query_predicates:
partition_count_now_and_horizon:
unique_fk_constraints:
late_and_future_data:
automation_owner:
evidence:
revisit_trigger:

D.2 ch07：规划时/执行时裁剪与父表统计

ch07.4 用 EXPLAIN 区分：

plan-time pruning
  常量/可折叠表达式在规划时排除 partition

execution-time pruning
  parameter/nested-loop value 在 executor 初始化或运行阶段排除

检查：

SHOW enable_partition_pruning;

EXPLAIN (ANALYZE, BUFFERS, SETTINGS, VERBOSE)
SELECT ...
FROM partitioned_parent
WHERE partition_key >= $1
  AND partition_key <  $2;

关注：

Subplans Removed
loops = 0
实际访问的 child relation
parent/child row estimates
planning time and partition count

常见裁剪失败

• predicate 没落在 partition key；
• 隐式 cast、时区或函数阻止匹配；
• wrapper/表达式与 partition bound 不同；
• generic/custom prepared plan 行为不同；
• join value 只能在执行阶段知道；
• default partition 覆盖过大；
• 误把 constraint exclusion 与 declarative pruning 混为一谈。

“查询结果快”不证明裁剪；小数据可能全扫仍快。保存 plan、参数、table definition、 statistics 和 server version。

statistics

parent/child 的 statistics、autovacuum/analyze 与增量数据分布可能不同。检查：

parent estimates vs actual
hot/current child statistics freshness
partition key and correlated columns
default partition skew
newly attached partition analyze state

不要只在一个 child ANALYZE 后推断 parent workload 已正确估算。

D.3 ch11：在线分区化

ch11.4 把“改成分区表”当迁移项目：

expand
  create partitioned parent, children, indexes, constraints

migrate
  backfill bounded ranges; capture concurrent delta

validate
  counts/digests/constraints/query plans/replica lag

cut over
  bounded lock; route old/new application versions

contract
  stop dual path; retain rollback; retire old table

PostgreSQL 不能把普通表原地无成本变成 partitioned parent。迁移策略可用新表、shadow write、logical change capture、短暂停写或 ATTACH PARTITION，但每种都要重新验证 锁、WAL、trigger/FK、sequence、replica 和 rollback。

ATTACH PARTITION

若待 attach 表已有能证明 bound 的匹配 CHECK constraint，PostgreSQL 可避免为验证 partition constraint 扫描它；具体锁与扫描行为绑定版本与对象状态。default partition 还可能需要验证它不含新 range 数据。执行前：

exact bound and no overlap
matching columns/types/collations
constraints and indexes
no rows outside bound
default partition impact
parent/child concurrent traffic
lock timeout and stop

attach 后再验证 parent query、direct child access、privilege、trigger、FK、stats 与 backup/replication。

dual write 风险

应用双写或 trigger capture 可能产生：

ordering difference
partial commit across systems
duplicate/retry
hidden trigger side effect
sequence drift
old/new schema incompatibility

优先同一 transaction 内可验证机制；仍需 source-of-truth、reconciliation 和 cutover watermark。不要以两个 row count 相等作为唯一证明。

D.4 ch16：时间分区场景

ch16.2 先定义时间：

event time       业务事件发生
ingest time      系统接收
effective time   业务事实生效
system time      数据库记录版本

partition key 必须匹配主要生命周期和查询。按 ingest time 分区容易接收 late event， 却不一定裁剪 event-time 查询；按 event time 分区需要 future/late/default 策略。

边界规则

store timestamptz for global instant
choose one canonical timezone for bounds
use half-open [from, to)
generate future partitions ahead of time
alert before current partition end
define late-arrival and backfill authority

不要用本地日期字符串猜 DST 边界。保存实际 bound：

SELECT
    inhparent::pg_catalog.regclass AS parent,
    inhrelid::pg_catalog.regclass AS child,
    pg_catalog.pg_get_expr(c.relpartbound, c.oid) AS bound
FROM pg_catalog.pg_inherits AS i
JOIN pg_catalog.pg_class AS c ON c.oid = i.inhrelid
WHERE inhparent = 'schema.parent'::pg_catalog.regclass
ORDER BY child::text;

partition 内索引

时间 range 裁剪减少 child 数，child 内仍要按谓词、排序和 join 选 B-tree/BRIN/GiST 等。 BRIN 依赖物理相关性，不是“时序表默认更快”；空间 + 时间查询还要验证两种 selectivity 如何组合。

D.5 ch28：分区生命周期、冻结与退役

ch28.5 把 partition state 作为有限状态机：

future -> writable -> sealed -> validated -> archived
       -> detached -> retained -> dropped

每次 transition 有：

partition:
bound:
state_before:
preconditions:
business_retention:
legal_hold:
backup_or_export:
freeze_and_visibility:
dependent_objects:
action:
validation:
rollback_or_re-attach:
owner:

sealed 不等于无需 vacuum

旧 partition 即使不再业务写入，仍可能需要：

• freeze XID/multixact；
• 清理过去更新留下的 dead tuple；
• 更新 visibility map；
• 完成 index/constraint validation；
• 处理仍引用它的 snapshot/slot/prepared transaction。

观察每个 child 的 age、stats 和 size，不只看 parent aggregate。

detach/drop 与大 DELETE

按完整 partition 退役通常能避免逐行 DELETE 的大量 WAL/dead tuples，但 DDL 仍有锁、 依赖、replication、backup 与业务风险。先确认：

bound fully outside retention
no legal/audit hold
archive/export is readable
queries no longer require it
FK/view/publication/privilege dependencies understood
exact partition identity
rollback window

DETACH 后对象仍占空间；DROP 才释放 relation，且是不可逆 schema/data action。不要 把 retention policy 直接变成无人审批的自动 drop。

五章闭环检查

ch04 decision still valid?
ch07 representative queries prune?
ch11 migration/cutover evidence retained?
ch16 time semantics and late data correct?
ch28 creation/seal/archive/drop automation healthy?

任一答案未知，先修生命周期合同，不急于增加 partition 数。

返回附录目录 · 对象与证据速查 · ch04 分区决策门 · 查看全书目录

附录 E：实验拓扑、风险与复位手册

本附录定义实验“在哪里运行、能改变什么、怎样回到可信状态”。它不是生产授权书； 每个章节的 lab contract 与当前环境 authority 优先。

E.1 L1/L2/L3 资源规格、网络和成本说明

L1：单节点学习环境

用途：ch01～ch18 的对象、SQL、应用与 extension PoC。默认单节点 meta 模板包含 PostgreSQL 与可观测组件，但不提供独立故障域或生产 HA。见第 0 章。

L2：四 VM 生产仿真

正式拓扑 pg36-l2-vagrant：

pg-meta-1  10.10.10.10  control + single PostgreSQL service
pg-test-1  10.10.10.11  pg-test primary at baseline
pg-test-2  10.10.10.12  pg-test replica
pg-test-3  10.10.10.13  pg-test replica/offline + disposable drill host

合同：

Pigsty v4.5.0 / PostgreSQL 18
Ubuntu 24.04 / aarch64 in formal run
UTC + synchronized clocks
data_checksums=on / UTF8 / C.UTF-8 / scram-sha-256 / SSL
distinct machine identities
minimum root free 8 GiB at acceptance

三台 pg-test VM 的正式教学运行只有 1 vCPU、约 1.9 GiB RAM；这被记录为 accepted sandbox exception。推荐至少给每个 PostgreSQL VM 2 vCPU / 2 GiB，控制/压测 client 使用 2 vCPU / 4 GiB 以上，并为 WAL、backup、clone 和 fixture 预留更多磁盘。

所有 VM 共享一台 laptop/hypervisor/power/storage，因此：

3 PostgreSQL members != 3 production failure domains
1 etcd member          != production DCS quorum
local MinIO/repository != offsite disaster recovery
virtual disk result    != production IOPS/durability

见 ch19 正式合同。

L3：从可信点分叉的事故现场

L3 不是“把 L2 破坏得更严重”，而是：

managed L2 read-only/controlled boundary
  +
stopped snapshot or deterministic source
  ->
private disposable case/working/recovery copies

第 32～35 章在 L2 host 上使用 exact UUID temporary root、private Unix socket、 非业务端口/无 TCP listener，并与 Patroni、DCS、HAProxy、PgBouncer、backup repository 和业务 route 隔离。L3 需要额外磁盘至少容纳 source + cases + working/recovery + evidence；运行前按 fixture 实测，而不是假定固定 8 GiB 足够。

网络

operator -> SSH to exact lab aliases
L2 internal 10.10.10.0/24 teaching network
service path and direct instance path both identifiable
disposable cluster listen_addresses='' where contract requires
no production route or public exposure

成本

本地成本来自 host RAM/CPU、磁盘、耗电与时间；云端另有 compute、volume/snapshot、 public IP、egress、object storage/API。价格随 region/日期变化，本书不冻结金额。每个 环境设置 owner、expiration 与 budget alert，并把保留 evidence 的费用计入。

E.2 R0–R3 风险标记

L1/L2/L3 描述实验环境；R0–R3 描述动作风险。两者不能互推：L3 中仍有 R0 查询，L1 上误删唯一数据仍是破坏性动作。

同一命令没有固定风险等级：在 disposable clone 上恢复一份 candidate 可以是 R2；让它 接管生产流量、覆盖真实目标或改变唯一权威时就是 R3。

风险升级因素

production data or traffic
target identity ambiguity
large or unknown scope
irreversible external effect
unique copy
weak/untested rollback
authority/lineage change
service restart or route change
long lock / resource saturation
secret or personal data exposure

任一因素都可能把看似普通命令升级。风险低不代表无成本：复杂 catalog query、 EXPLAIN ANALYZE、日志导出也可能造成负载或泄露。

guard 不是免责声明

target:
environment:
production_data:
production_traffic:
scope:
confirmation:
authority:
rollback_source:

guard 必须在 mutation 前解析并 fail closed。设置 I_KNOW_WHAT_I_AM_DOING=true 这种通用 token 不证明 target 或 authority。

各章脚本还可能使用 L0/L1/L2/L3 表示其内部 mutation level；以对应 lab-contract.md 定义为准，不与拓扑层级混用。

E.3 reset:sql、reset:cluster、reset:host

三种复位不是强度旋钮

名称是全书实验合同类别，不保证每章存在同名脚本。

reset:sql

前置：

current database/role/system identity match
owned object manifest complete
no production data/traffic
dependent session/job stopped
only pg36 chapter namespace/object selected

执行后验证 object absent/recreated、其他 schema digest 不变、connection context 仍正确。 用明确对象列表，不使用模糊 wildcard/cascade。

reset:cluster

可能包含：

remove exact fixture sessions/roles/schema
restore parameter and pending_restart state
restore Patroni role/topology baseline
restore HAProxy/PgBouncer route
re-enable archive/backup/monitoring/automation
reconcile temporary privilege and secret

先生成 plan，逐项 before/after。计划切换后的 baseline restore 仍是 HA 变更，需要 authority 和 client validation；不是测试清理的附带步骤。

reset:host

只有当 OS、storage、package 或 PostgreSQL 基线不再可信才进入：

preserve/hash evidence outside target
fence host from writer authority and routes
prove trusted backup or healthy source
pin inventory/release/packages/secrets
obtain destructive production approval
provision clean host/storage
restore or join as fresh replica
validate lineage, backup, monitoring, business
observe before traffic

不要复用 suspect PGDATA，不删除唯一 evidence。第 35 章只生成 l3-rebuild-plan.json，没有执行 managed reset:host。

reset 也需要验证器

exact target resolved
owned fixture removed
unrelated object/topology unchanged
temporary process stopped
route/automation restored
retained evidence still present
cleanup path exact

“脚本执行完”不等于 baseline 已恢复。

E.4 随机种子、快照、校验和与故障场景清单

可复现 fixture

generator_revision:
seed:
row_count:
distribution:
time_anchor:
locale_timezone:
scale:
expected:
  counts:
  sums:
  ordered_digest:

固定 seed 不足以保证相同结果；generator、PRNG、locale、timezone、dependency 与输入 排序都要固定。摘要至少组合 row count、关键 sum/range 与确定顺序 digest。

snapshot 树

known-good immutable source
  -> case-A original
     -> working-A1
     -> working-A2
  -> case-B original
     -> recovery-B

记录 snapshot ID、parent、created_at、filesystem/database consistency、system identifier/timeline projection 和 hash。实验只改 case/working，known-good 与 original 在结论完成前保持不变。

checksum 的四种含义

它们不能互换。hash 匹配不证明来源可信，business digest 不证明每个 page 可读。

场景清单

scenario_id:
hidden_truth:
public_packet:
allowed_mutations:
forbidden_targets:
required_evidence:
classifier_predicates:
unknown_route:
safe_actions:
dangerous_actions:
cleanup:
claims_not_made:

blind exercise 把 hidden truth 与 participant/classifier input 分离；场景 source 在公开 教材中不是密码学秘密，正式考核由主持人控制访问或生成私有 seed。

evidence bundle

contract + source manifest
environment identity
before / during / after
blind packet + hidden answer
decision/classification
business manifest
negative cases
cleanup
redacted public summary

raw logs、PGDATA、query payload、credentials 和个人数据留在受控 evidence store， 仓库只发布去敏 projection。

返回附录目录 · 症状索引 · 术语边界 · 查看全书目录

附录 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.5.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 章全局地图 · 查看全书目录