返回所有指南
数据库设计··阅读约需 3 分钟

数据库文档:用 ERD 说明 SQL 模式

使用 ERD、SQL 示例、关系注释和迁移上下文记录数据库模式,以便团队能够更快地理解数据模型。

客户到订单图,旁边附有解释外键和业务规则的注释
在本指南中
  1. 为什么数据库文档会失败
  2. 模式文档中应包含什么
  3. 示例文档块
  4. 实用的文档工作流
  5. 参考资料与延伸阅读

除非另外命名了方言,否则 SQL 示例使用 PostgreSQL。简短的代码片段假定其引用的表已存在。在应用 DDL 之前,请在目标数据库中验证 DDL。

为什么数据库文档会失败

数据库文档经常过时,因为它是与架构分开编写的。有人在第一个设计冲刺期间创建了一个图表,数据库更改了六个月,文档悄悄地变得具有误导性。

更好的方法是将文档保持在靠近 SQL 源的位置。从 DDL 生成图表,为表和关系添加简短的解释,并在模式更改时更新文档。

SQL 架构、ERD 图表、关系注释和迁移上下文合并到文档中
强大的数据库文档将 SQL 源与 ERD 和简短的关系注释配对,因此文档保持实用。

模式文档中应包含什么

有用的数据库文档可以回答开发人员在构建功能和调试生产数据时实际提出的问题。

  • 一个 ERD。 显示表、主键、外键和主要关系路径。
  • 表用途说明。 解释每个主要表存在的原因以及哪个功能拥有它。
  • 关系规则。 明确基数、可选关系和级联操作。
  • 重要约束。 记录唯一键、检查、枚举值以及由 SQL 强加的业务规则。
  • 迁移上下文。 将架构更改与背后的功能、bug 修复或运营原因关联起来。

示例文档块

轻量级文档条目可以将 SQL 与用通俗语言编写的注释配对:

CREATE TABLE accounts (
    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name TEXT NOT NULL
);

CREATE TABLE invoices (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    account_id  BIGINT NOT NULL REFERENCES accounts (id),
    status      VARCHAR(30) NOT NULL DEFAULT 'draft',
    total       NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
    due_date    DATE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE invoice_payments (
    id          BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    invoice_id  BIGINT NOT NULL REFERENCES invoices (id) ON DELETE CASCADE,
    amount      NUMERIC(12, 2) NOT NULL CHECK (amount > 0),
    paid_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

文档说明可能会指出:一个账户有多张发票,发票有多条支付记录,并且如果删除了测试发票,支付行也会被删除。在具有审计要求的生产系统中,您可能会将级联删除替换为受限删除和归档记录。

实用的文档工作流

这是一个既能保持文档有用又不至于将编写文档变成全职工作的工序流。

  • 从 SQL 模式开始,在...中生成 ERD Erd Go 编辑器.
  • 当架构适合公开访问时,导出图表或登录、保存并共享只读公开链接。对于私密文档,请使用图像导出。
  • 为每个重要的表集群添加一个简短的段落:auth、billing、orders、content、audit 或 reporting。
  • 在迁移过程中从更新后的 SQL 重新生成 ERD,以便文档反映出更改内容。
  • 使语法示例与以下内容保持同步: Erd Go DDL 文档 以便未来的贡献者可以重现该图。

目标不是一个完美的百科全书。目标是创建一个活的地图,帮助人们快速理解数据库并信任他们所读的内容。

参考资料与延伸阅读

更多文章