mcpField
D
dbml-database-docs

dbml-database-docs

github.com/aircury数据与数据库5108 次安装2 天前更新
代码仓库

关于 dbml-database-docs

dbml-database-docs 是维护 DBML 数据库结构文档的技能，面向处理模式变更或文档的仓库贡献者。它将 `db/schema.dbml` 作为规范记录，并指导记录结构细节和检查偏差。

主要功能

  1. 01以 `db/schema.dbml` 为规范文档
  2. 02记录表与列
  3. 03记录键、关系和索引
  4. 04审查模式来源的工作流
  5. 05模式偏差验证指引

适用场景

  1. 01记录数据库模式变更
  2. 02对照迁移审查 DBML
  3. 03修复模式文档偏差

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aircury/ai-framework --skill dbml-database-docs

安装后在 Claude Code 中输入/dbml-database-docs确认已加载。

详细介绍

DBML 数据库文档

你负责确保数据库结构以 DBML 格式记录。

只要任务涉及数据库结构或数据库文档，就使用 DBML 作为数据库架构的规范表示，供人和 AI 阅读。

规范文件

规范数据库文档文件为：

db/schema.dbml

如果仓库中的数据库架构文档采用其他格式，且用户未明确要求保留该格式，请将结构性架构文档迁移或整合到 db/schema.dbml 中。

其他文档仅用于辅助说明。适合使用 DBML 时，不要让 Mermaid 图、Prisma 架构文件、Markdown 表格、ORM 元数据或文字摘要成为规范数据库文档。

何时使用此技能

用户提出以下任一需求时，请使用此技能：

  • 数据库文档。
  • 数据库架构文档。
  • ERD 或实体关系文档。
  • 表、列、关系、外键或索引文档。
  • SQL、迁移、Doctrine 实体、ORM 模型或数据库元数据的文档。
  • 审查数据库文档是否与迁移或实时架构一致。
  • 修复与架构漂移或 DBML 漂移有关的 CI 失败。
  • 添加、更改或审查结构性数据库变更。

结构性数据库变更包括：

  • 新增或更改迁移。
  • 新增、重命名、更改或删除表。
  • 新增、重命名、更改或删除列。
  • 更改列类型、可空性、默认值、生成值或注释。
  • 新增、更改或删除主键、外键、唯一约束、检查约束、索引或枚举。
  • 更改联接表、继承表、审计表或查找表。

核心规则

只要工作涉及结构性数据库变更，就必须在同一工作单元中更新 db/schema.dbml。

不要在更改迁移、ORM 元数据或 SQL 架构后遗漏相应的 DBML 更新。否则会造成文档漂移，导致未来的 AI 会话依据过时的持久化契约进行推理。

工作流

  1. 检查仓库现有的数据库事实来源。
  2. 确定实际生效的结构性架构。
  3. 使用当前架构契约创建或更新 db/schema.dbml。
  4. 在 specs/features/ 中保留行为要求；DBML 只记录持久化结构。
  5. 在可行时运行相关的验证命令。
  6. 如果漂移检查失败，应修复不一致，而不是绕过检查。

潜在的架构来源包括：

  • Doctrine 迁移。
  • Doctrine 实体映射或属性。
  • SQL 迁移文件。
  • ORM 模型定义。
  • 数据库转储或架构快照。
  • 现有 DBML 文件。
  • CI 漂移检查脚本。

优先采用生成的数据或由迁移支持的事实，避免猜测。如果无法根据现有文件确认架构，请在 DBML 注释中标明不确定之处，或向用户索取缺失的来源。

DBML 内容要求

存在或可推断时，请记录以下细节：

  • 表。
  • 列。
  • 列类型：在可行时使用数据库的实际类型词汇。
  • not null 约束。
  • 主键。
  • 外键和关系基数。
  • 唯一约束。
  • 索引，包括复合索引和唯一索引。
  • 默认值。
  • 枚举或受约束的值集。
  • 有意义的数据库注释或备注。
  • 联接表和多对多关系。
  • 属于架构契约的审计列或时间戳列。

名称必须保持原样。编写文档时，不要现代化、重命名、规范化或重新解释数据库对象。

DBML 风格

使用清晰且便于审查差异的 DBML：

Table users {
  id uuid [pk]
  email varchar(255) [not null, unique]
  created_at timestamp [not null]
}

Table orders {
  id uuid [pk]
  user_id uuid [not null]
  total_amount decimal(10,2) [not null]

  Indexes {
    (user_id)
  }
}

Ref: orders.user_id > users.id

使用 Note: 记录属于持久化契约的说明，而非一般产品行为：

Table subscriptions {
  id uuid [pk]
  status varchar(32) [not null, note: 'Allowed by application policy: active, paused, cancelled']
}

如果数据库强制执行某条规则，请在 DBML 支持的情况下以结构化方式表示。如果应用程序强制执行的规则与持久化相关，但 DBML 无法直接建模，请添加简洁的注释。

关系规则

优先使用显式的 Ref: 声明表示关系：

Ref: order_items.order_id > orders.id
Ref: order_items.product_id > products.id

确保外键名称、引用列和可空性保持一致。可选关系应使用可空的外键列；必需关系应使用 [not null]。

索引规则

在每个表的 Indexes 块中表示索引：

Table users {
  id uuid [pk]
  tenant_id uuid [not null]
  email varchar(255) [not null]

  Indexes {
    (tenant_id, email) [unique]
    (email)
  }
}

不要因为索引未显示在实体字段中就将其省略。索引是持久化契约的一部分，通常承载着重要的查询和唯一性假设。

漂移检查

如果仓库中包含此脚本，请将其用作数据库文档漂移检查门禁：

./scripts/check-schema-drift.sh

可行时，在更新 db/schema.dbml 后运行该脚本。如果运行失败，请检查失败原因，并确保实际数据库架构与 db/schema.dbml 一致。

除非用户在你说明风险后明确要求，否则不要禁用检查、放宽 CI、跳过钩子，或将失败标记为无关问题。

CI 失败处理

当用户报告 CI 架构漂移失败时：

  1. 阅读 CI 输出，确定过时的是实时／生成的架构、迁移文件还是 db/schema.dbml。
  2. 对比相关迁移文件或架构快照与 db/schema.dbml。
  3. 更新过时的一方。
  4. 如果有 ./scripts/check-schema-drift.sh，请重新运行。
  5. 总结已重新同步的架构对象。

与功能规格的边界

使用 db/schema.dbml 记录持久化结构。 使用 specs/features/ 记录可观察到的系统行为。

示例：

  • users.email 唯一索引应记录在 db/schema.dbml 中。
  • 解释用户何时可以更改邮箱的业务规则应记录在 specs/features/ 中。
  • 从 orders.user_id 指向 users.id 的外键应记录在 db/schema.dbml 中。
  • 创建订单的结账行为应记录在 specs/features/ 中。

当结构和行为都发生变化时，请同时更新两个文件。

完成检查清单

完成数据库文档工作前，请确认：

  • 需要数据库架构文档时，db/schema.dbml 已存在。
  • 已记录所有涉及的表、列、外键、唯一约束和索引。
  • DBML 名称与实际数据库名称完全一致。
  • 结构性数据库更改与 DBML 更改已一并提交。
  • 适用时，相关行为更改已反映在 specs/features/ 中。
  • 如果存在且可行，已运行 ./scripts/check-schema-drift.sh。

评论

支持 Markdown