导读

本文以开源仓库 architecture-decision-record 中收录的西班牙语示例文档 base-de-datos-postgresql 为骨架，完整解读一篇"数据库选型"类 ADR 的标准写法：从背景陈述、决策声明、五大选型理由到备选方案与结论。读完本文，你将掌握如何把 PostgreSQL 与 MySQL 这类技术选型讨论，沉淀为一份结构清晰、可追溯、对后续开发者有长期价值的 Architecture Decision Record，并了解如何结合仓库中的命名规范、模板与 git 流程在自己的项目中落地实践。

一、为什么数据库选型需要一份 ADR

在 architecture-decision-record 项目的定义中，架构决策记录（Architecture Decision Record，ADR）是一份"记录重要架构决策及其背景与后果"的文档（参见 qué-es-un-registro-de-decisión-de-arquitectura）。数据库管理系统（DBMS）的选择恰恰是典型的架构级决策（Architecture Decision，AD）：它直接决定系统的数据结构、事务模型、扩展方式与运维形态，一旦选型定型，后期更换成本极高。

仓库自带的 Claude Code 技能 architecture-decision-record-skill 给出了判断"什么决策值得写 ADR"的三条标准，数据库选型几乎全部命中：

• 架构意义重大：影响系统结构、外部接口与质量属性，且难以低成本逆转；
• 需要让不在场的人理解"为什么"：未来加入项目的开发者需要知道当初为何选 PostgreSQL 而不是 MySQL；
• 存在真实的权衡取舍：这不是一行代码风格问题，而是需要记录论据的功能与性能比较。

反之，小范围、自包含、单开发者、已被标准或策略覆盖、纯临时性的决策（如临时 workaround、POC）则不需要 ADR。数据库选型显然属于"应该写"的那一类，这正是仓库把 PostgreSQL 与 MySQL 各收录一篇独立示例的原因。

二、示例文档背景：一次从候选清单到结论的选型过程

原文档（西班牙语版 index.md）的Contexto（背景）部分这样写道：

我们组织目前正在评估最适合下一个项目的数据库管理系统选项。我们已经把搜索范围缩小到两个选项——PostgreSQL 和 MySQL。经过仔细考虑，我们决定使用 PostgreSQL，因为它具有高级功能和性能能力。

这一段的写法完全符合仓库在 sugerencias-para-escribir-buenos-adr 中给出的"好 Context 标准"：

• 说明组织现状与业务优先级：明确"正在为下一个项目选型"这一业务背景；
• 交代候选范围：不是罗列市场上所有数据库，而是"缩小到两个选项"，表明已完成初步筛选；
• 给出初步倾向及理由：提前点明"高级功能与性能能力"这两个核心考量维度。

注意，这份示例并未堆砌大量无关信息，而是用两三句话把"组织要做什么、在哪些选项之间选、倾向是什么"交代清楚——这正是 architecture-decision-record-skill 反复强调的：Context 应解释组织的处境、约束与张力，而不是只写一句"我们需要一个数据库"。

三、决策声明（Decisión）：清晰、不模棱两可

原文档的Decisión（决策）部分只有一句话，却是一份 ADR 中最关键的表述：

我们将使用 PostgreSQL 作为我们组织下一个项目的首选数据库管理系统。

对照 architecture-decision-record-skill 的写作要求："Decision 应该直接陈述所选方向，而不是含糊其辞"，这段声明做到了三点：

1. 主语明确：决策主体是"我们组织"；
2. 对象明确：选中的是 PostgreSQL，角色是"首选数据库管理系统"；
3. 范围明确：针对"下一个项目"，而不是抽象地宣布全公司统一用某一种数据库。

仓库中另一篇数据库选型示例 elección-de-una-tecnología-de-base-de-datos 还示范了在决策前先声明Estado（状态）为 Aceptado（已接受）的做法。ADR 常见的状态值包括 proposed（提议）、accepted（已接受）、rejected（已拒绝）、deprecated（已弃用）、superseded by …（被……取代），这可以帮助团队追踪每项决策的生命周期。

四、五大选型理由（Justificación）：逐条解读

原文档的Justificación（理由）部分列出了选择 PostgreSQL 的五个理由，这是整份 ADR 信息密度最高的部分，也是搜索引擎与后续读者最常引用的内容。

1. 高级功能（Funciones avanzadas）

PostgreSQL 拥有广泛的高级功能，如 JSON 支持、全文搜索和空间数据管理，这些对我们的项目至关重要。

这一条把 PostgreSQL 的三个标志性能力作为选型依据：

• JSON 支持：PostgreSQL 提供json与jsonb数据类型，可在关系模型内直接存储和查询半结构化数据，兼顾关系约束与文档灵活性；
• 全文搜索（full-text search）：内置tsvector/tsquery全文检索能力，减少对独立搜索引擎的依赖；
• 空间数据管理：通过 PostGIS 等扩展提供地理空间数据能力。

对于需要同时处理结构化业务数据与非结构化数据的项目，这一条往往具有决定性意义——它意味着不必为了某一种数据形态引入第二套数据库。

2. 性能（Rendimiento）

PostgreSQL 在出色的性能能力方面有着经过验证的记录，这将确保我们的项目顺利运行，不会出现性能问题。

该理由强调的是"经过验证的记录"（historias probadas de rendimiento）。在 ADR 中记录性能考量时，仓库在 sugerencias-para-escribir-buenos-adr 中特别提醒：涉及成本、进度、扩展规模等可能随时间变化的信息，必须打上时间戳（Timestamps）。性能数据会随版本、硬件与负载模型变化，因此一份严谨的 ADR 应在该条目后注明评估时点与依据，避免把"当时的测试结论"误传为永久事实。

3. 社区支持（Apoyo de la comunidad）

PostgreSQL 拥有庞大而活跃的社区，提供定期更新和支持，使解决项目开发阶段出现的任何问题变得更容易。

社区活跃度直接关系到问题解决速度与人才可获取性：活跃的社区意味着更频繁的版本发布、更快的安全补丁、更丰富的第三方工具链和更易检索的排错资料。这一条在实际选型中常与"团队技能储备"叠加考虑。

4. 可扩展性（Escalabilidad）

PostgreSQL 具有高度可扩展性，可以轻松处理大量数据，这对我们的项目至关重要。

可扩展性是数据密集型项目选型的核心考量。需要说明的是，该示例在原文中并未给出具体的架构手段（如分区、读写分离、复制等），因此在引用时不应过度演绎，可以将其理解为"PostgreSQL 提供了分区表、流复制、逻辑复制等横向与纵向扩展手段，使其具备承载大数据量的能力"，具体方案应作为后续 ADR 进一步细化。

5. 安全性（Seguridad）

PostgreSQL 拥有强大的安全机制，将确保我们的项目数据始终安全，并满足我们组织的所有安全要求。

该条目点明两层含义：一是 PostgreSQL 自身的安全能力（认证、权限、加密等），二是与组织安全合规要求的匹配。在正式 ADR 中，这一条通常应展开为具体的合规要求清单（如加密标准、审计日志、访问控制模型），并对照能力逐项勾选。

五项理由的归纳

把五条理由放在一起可以看出这篇示例的结构技巧：每一条都以"能力 → 为什么对我们项目重要"的形式组织，让理由不只是功能罗列，而是与项目需求建立了明确关联。这也正是好 ADR 的"Rationale（论证）"特征——解释"为什么做这个决策"，而不是简单陈述"做了什么"。

五、备选方案（Alternativas）：与 MySQL 的对照分析

原文档的Alternativas（备选方案）部分给出了被否决选项的陈述：

我们考虑的另一个选项是 MySQL。MySQL 也是一个非常强大的数据库管理系统，但它缺少 PostgreSQL 提供的一些高级功能，而且其性能能力不如 PostgreSQL。

这段对比虽然简短，却承担了 ADR 中**记录"已考虑过什么"**的关键职责。仓库中的 base-de-datos-mysql 示例则从 MySQL 视角提供了更完整的对照框架，两者可以互相印证。把两份示例对照阅读，可得到如下选型维度：

值得注意的一点是：这两篇示例分别从各自立场陈述了对方的相对短板，恰好演示了 ADR 写作中"在 Context 中如实记录 pros/cons"的原则——否决选项的理由写得越具体，日后重审决策时的依据就越充分。仓库文档还提醒，备选方案部分最好注明比较的时点与依据，因为数据库功能与性能随版本演进，多年后回看时需结合当时背景理解。

六、结论（Conclusión）：决策的收束与后续

原文档的Conclusión（结论）部分完成了决策的闭环：

基于我们的分析，我们决定使用 PostgreSQL 作为我们组织下一个项目的首选数据库管理系统。这一决定是经过深思熟虑后做出的，我们相信它将帮助我们高效、有效地实现项目目标。

在真实项目中，结论之后通常还应接续"Consecuencias（后果）"部分。参考仓库文档 sugerencias-para-escribir-buenos-adr 的建议，后果部分应涵盖：

• 带来的正面影响：例如获得 JSON 与全文检索能力、安全合规达标；
• 带来的成本与约束：例如团队需要补齐 PostgreSQL 运维技能、迁移期间的双轨运行；
• 后续 ADR：大决策往往催生小决策——数据库选型确定后，可能接着需要就"连接池方案""备份策略""读写分离架构"各立一份 ADR；
• 事后复盘：建议团队在决策实施约一个月后回头对比 ADR 记录与实际运行情况，持续学习改进。

七、把这篇示例落地为自己的 ADR：命名、模板与 git 流程

原文档只是示例，真正落地时需要把它改写成属于自己项目的 ADR。仓库为此提供了完整的配套流程。

1. 按命名约定创建文件

仓库在 convenciones-de-nombres-de-archivo 中给出了推荐的文件命名约定，本文示例的英文版正对应postgresql-database这类命名：

• 文件名使用现在时祈使动词短语，如choose-database.md、format-timestamps.md，便于阅读且与 commit message 风格一致；
• 使用小写与连字符，兼顾可读性与系统可用性；
• 扩展名为.md，便于格式化和版本管理。

2. 选择合适的模板

仓库在 plantillas 目录下收录了多种 ADR 模板。其中与本示例结构最接近的是Michael Nygard 模板（Title / Status / Context / Decision / Consequences），本文解析的 PostgreSQL 示例本质上就是该模板的变体。若团队希望更严谨地比较多个备选方案，可以选用 plantilla-de-registro-de-decisión-del-proyecto-madr，它额外提供"决策因素（Factores de decisión）""考虑过的选项（Opciones consideradas）""各选项的优缺点（Ventajas y desventajas de las opciones）"等章节，非常适合数据库这类需要多维度比较的决策。

architecture-decision-record-skill 给出了模板选择速查表：默认团队用 Nygard；需要轻量级"选项+优缺点"用 MADR；企业级需要需求/原则追溯用 Tyree & Akerman；需要成本、SWOT 与多方意见时用 Business case 模板。数据库选型场景下，Nygard 与 MADR 通常是最佳起点。

3. 用 git 管理 ADR 文件

仓库文档 cómo-empezar-a-usar-adr-con-git 给出了最简流程：

$ mkdir adr $ vi choose-database.md

即：为 ADR 建一个目录，每个决策对应一个 Markdown 文件，写好内容后提交（commit）到 git 仓库。git 带来的版本历史、评审（PR）流程与责任追溯，正是 ADR"不可变 + 可追溯"特性的天然载体。

4. 遵循 ADR 通用写作规范

无论选用哪个模板，都应以仓库 sugerencias-para-escribir-buenos-adr 的四条标准自检：Rationale（论证充分）、Specific（一 ADR 只讲一个决策）、Timestamps（时间敏感信息标注时点）、Immutable（不改旧文，以追加或新 ADR 取代）。当新决策取代旧决策时，正确的做法不是悄悄编辑旧文件，而是新建 ADR 并把旧 ADR 的状态标记为"已被取代（Superseded by …）"，同时在新 ADR 中反向链接"取代了（Supersedes …）"。

八、仓库中的相关资源导航

若想继续深入，可从以下仓库路径获取配套资料：

• 本文解析的原文档：locales/es-001/ejemplos/base-de-datos-postgresql/index.md（另有英文版 locales/en-001/examples/postgresql-database/index.md）；
• MySQL 对照示例：locales/es-001/ejemplos/base-de-datos-mysql/index.md；
• 数据库技术大类选型示例：locales/es-001/ejemplos/elección-de-una-tecnología-de-base-de-datos/index.md；
• 全部示例索引：locales/es-001/ejemplos/index.md；
• 模板索引：locales/es-001/plantillas/；
• ADR 写作规范：locales/es-001/documentos/sugerencias-para-escribir-buenos-adr/index.md；
• 文件命名约定：locales/es-001/documentos/convenciones-de-nombres-de-archivo/index.md；
• git 入门流程：locales/es-001/documentos/cómo-empezar-a-usar-adr-con-git/index.md；
• 面向 AI 编码 Agent 的 ADR 写作技能：skills/architecture-decision-record-skill/SKILL.md。

结语

这篇 PostgreSQL 选型示例的价值不在于替你做决定，而在于示范了如何把一次技术选型从"会议室里的讨论"沉淀为"仓库里可检索、可追溯、可复用的事实"。背景交代候选范围、决策声明明确指向、理由逐条与项目需求挂钩、备选方案如实记录否决原因、结论收束闭环——五段式结构本身就可以直接套用到你自己的数据库选型、框架选型、云服务选型等任何架构级决策上。参照仓库的命名约定与模板，把它改写为choose-database.md提交进你的 git 仓库，你的下一个项目成员就能准确理解"为什么是 PostgreSQL"。