# 扩展 ADR 模板

> 把“扩展名”换成“要解决的问题”作为标题。扩展只是候选解，不是需求本身。

## 1. 决策元数据

- ADR ID：
- 状态：proposed / pilot / accepted / rejected / superseded
- 负责人：
- 决策日期：
- 复审日期：
- 适用 PostgreSQL、操作系统、架构与 Pigsty 版本：

## 2. 问题与边界

- 哪个已观测问题需要解决？
- 当前规模、查询形态、SLO 和失败成本是什么？
- 哪些场景明确不在本次范围？
- 不做任何改变会发生什么？

## 3. 候选与原生替代

- PostgreSQL 原生数据类型、索引、分区、全文检索或应用实现能否满足？
- 候选扩展提供了哪项不可替代能力？
- 其他扩展、外部服务和托管能力各有什么代价？

## 4. 成功与停止标准

- 正确性、质量、延迟、吞吐、资源与恢复指标：
- 通过阈值：
- 停止试点阈值：
- 证据采集方式与数据集版本：

## 5. 供应链与运行条件

- 扩展名、软件包别名、OS 包名、数据库对象版本：
- 支持的 PostgreSQL/OS/CPU 架构：
- control 文件属性：`superuser`、`trusted`、`relocatable`、`requires`：
- 是否需要 `shared_preload_libraries` 与重启：
- 所有主库、备库、恢复节点是否同构：
- 包、control/SQL 脚本与动态库哈希：

## 6. 数据与兼容性

- 是否引入自定义类型、访问方法、WAL 行为或 catalog：
- `pg_dump`/恢复、逻辑复制、物理复制和 `pg_upgrade` 条件：
- 扩展更新路径与锁、停机、回滚约束：
- 是否存在向后不兼容的数据格式变更：

## 7. 安全与治理

- 谁能安装、创建、升级、删除扩展：
- 安装脚本以谁的权限执行：
- C 扩展的崩溃面与供应链来源：
- 许可证、维护活跃度、漏洞响应与商业连续性：
- 监控、日志、告警和责任人：

## 8. 最小 PoC

- fixture/数据快照：
- 对照组与基线：
- 成功查询和计划：
- 必须出现的失败：
- 备份恢复与升级演练：
- 证据目录及校验和：

## 9. 退出路径

- 先导出为何种原生、文本或交换格式：
- 哪些列、索引、函数和查询需要迁移：
- 双写或回填顺序：
- 回退点与不可逆步骤：
- 清退包、预加载配置和数据库对象的顺序：

## 10. 结论

- 决策及理由：
- 被拒候选及理由：
- 残余风险：
- 上线前置条件：
- 复审触发器：