dbml-database-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DBML Database Documentation

DBML数据库文档

You are responsible for keeping the database structure documented in DBML.

Use DBML as the canonical, human- and AI-readable representation of the database schema whenever the task touches database structure or database documentation.

您负责维护DBML格式的数据库结构文档。

每当任务涉及数据库结构或数据库文档时，请将DBML作为数据库架构的标准、人类与AI均可读取的表示形式。

Canonical File

标准文件

The canonical database documentation file is:

text

db/schema.dbml

If the repository has database schema documentation in another format and the user has not explicitly asked to preserve that format, migrate or consolidate the structural schema documentation into

db/schema.dbml

Use other docs only as supporting explanation. Do not let Mermaid diagrams, Prisma schema files, Markdown tables, ORM metadata, or prose summaries become the canonical database documentation when DBML is appropriate.

标准数据库文档文件为：

text

db/schema.dbml

如果仓库中存在其他格式的数据库架构文档，且用户未明确要求保留该格式，请将结构化架构文档迁移或整合至

db/schema.dbml

中。

仅将其他文档用作辅助说明。当DBML适用时，请勿让Mermaid图、Prisma架构文件、Markdown表格、ORM元数据或纯文字摘要成为标准数据库文档。

When To Use This Skill

何时使用此规范

Use this skill when the user asks for any of these:

Database documentation.
DB schema documentation.
ERD or entity relationship docs.
Table, column, relation, foreign key, or index documentation.
Documentation for SQL, migrations, Doctrine entities, ORM models, or database metadata.
A review of whether database docs match migrations or the live schema.
Fixing CI failures related to schema drift or DBML drift.
Adding, changing, or reviewing structural database changes.

Structural database changes include:

New or changed migrations.
New, renamed, altered, or removed tables.
New, renamed, altered, or removed columns.
Changed column types, nullability, defaults, generated values, or comments.
New, changed, or removed primary keys, foreign keys, unique constraints, checks, indexes, or enums.
Join-table, inheritance-table, audit-table, or lookup-table changes.

当用户提出以下任一需求时，请使用此规范：

数据库文档
数据库架构文档
ERD（实体关系图）或实体关系文档
表、列、关联、外键或索引文档
SQL、迁移、Doctrine实体、ORM模型或数据库元数据的文档
审核数据库文档是否与迁移或实时架构匹配
修复与架构漂移或DBML漂移相关的CI故障
添加、变更或审核数据库结构变更

数据库结构变更包括：

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

Core Rule

核心规则

Whenever a structural database change is part of the work, update

db/schema.dbml

in the same unit of work.

Do not leave a migration, ORM metadata change, or SQL schema change without the corresponding DBML update. That creates documentation drift and makes future AI sessions reason from stale persistence contracts.

每当工作中涉及数据库结构变更时，请在同一工作单元内更新

db/schema.dbml

。

请勿在完成迁移、ORM元数据变更或SQL架构变更后，不进行对应的DBML更新。这会导致文档漂移，使后续AI会话基于过时的持久化契约进行推理。

Workflow

工作流程

Inspect the repository's existing database source of truth.
Identify the effective structural schema.
Create or update
```
db/schema.dbml
```
with the current schema contract.
Preserve behavioural requirements in
```
specs/features/
```
; keep DBML focused on persistence structure.
Run the relevant verification command when available.
If a drift check fails, fix the mismatch rather than bypassing the check.

Potential schema sources include:

Doctrine migrations.
Doctrine entity mappings or attributes.
SQL migration files.
ORM model definitions.
Database dumps or schema snapshots.
Existing DBML files.
CI drift-check scripts.

Prefer generated or migration-backed facts over guesswork. If the schema cannot be proven from the available files, mark the uncertainty in a DBML note or ask the user for the missing source.

检查仓库中现有的数据库真实数据源
确定有效的结构化架构
创建或更新
```
db/schema.dbml
```
以记录当前架构契约
将行为需求保留在
```
specs/features/
```
目录中；DBML仅聚焦于持久化结构
若有可用的相关验证命令，请运行该命令
若漂移检查失败，请修复不匹配项，而非绕过检查

潜在的架构数据源包括：

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

优先基于生成的或迁移支持的事实，而非猜测。若无法从现有文件中确认架构，请在DBML注释中标记不确定性，或向用户询问缺失的数据源。

DBML Content Requirements

DBML内容要求

Represent these details when present or inferable:

Tables.
Columns.
Column types using the database's real type vocabulary where practical.
```
not null
```
constraints.
Primary keys.
Foreign keys and relationship cardinality.
Unique constraints.
Indexes, including composite indexes and uniqueness.
Defaults.
Enums or constrained value sets.
Meaningful database comments or notes.
Join tables and many-to-many relationships.
Audit or timestamp columns when they are part of the schema contract.

Keep names exact. Do not modernise, rename, normalise, or reinterpret database objects while documenting them.

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

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

保持名称完全一致。记录数据库对象时，请勿对其进行现代化、重命名、规范化或重新解释。

DBML Style

DBML风格

Use clear DBML that favours reviewable diffs:

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

Use

Note:

for explanations that are part of the persistence contract, not for general product behaviour:

dbml

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

If the database enforces a rule, represent it structurally where DBML supports it. If the application enforces a persistence-relevant rule that DBML cannot model directly, add a concise note.

使用清晰的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:

记录属于持久化契约的说明，而非通用产品行为：

dbml

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

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

Relationship Rules

关联规则

Prefer explicit

Ref:

declarations for relationships:

dbml

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

Keep foreign key names, referenced columns, and nullability consistent. Optional relationships should have nullable FK columns; required relationships should use

[not null]

优先使用显式的

Ref:

声明关联：

dbml

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

保持外键名称、引用列和非空性一致。可选关联应使用可空的FK列；必填关联应使用

[not null]

。

Index Rules

索引规则

Represent indexes in each table's

Indexes

block:

dbml

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

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

Do not omit indexes because they are not visible in entity fields. Indexes are part of the persistence contract and often encode important lookup and uniqueness assumptions.

在每个表的

Indexes

块中记录索引：

dbml

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

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

请勿因索引未在实体字段中显示而省略。索引是持久化契约的一部分，通常包含重要的查询和唯一性假设。

Drift Checks

漂移检查

If the repository contains this script, use it as the database documentation drift gate:

bash

./scripts/check-schema-drift.sh

Run it after updating

db/schema.dbml

when feasible. If it fails, inspect the failure and make the actual database schema and

db/schema.dbml

agree.

Do not disable the check, weaken CI, skip hooks, or mark the failure as unrelated unless the user explicitly instructs you to do so after you explain the risk.

若仓库包含以下脚本，请将其用作数据库文档漂移检查的入口：

bash

./scripts/check-schema-drift.sh

若可行，请在更新

db/schema.dbml

后运行该脚本。若检查失败，请排查故障并使实际数据库架构与

db/schema.dbml

保持一致。

除非用户在您解释风险后明确指示，否则请勿禁用检查、弱化CI、跳过钩子或标记故障为无关问题。

CI Failure Handling

CI故障处理

When the user reports a CI schema drift failure:

Read the CI output and identify whether the live/generated schema, migrations, or
```
db/schema.dbml
```
is stale.
Compare the relevant migrations or schema snapshot against
```
db/schema.dbml
```
.
Update the stale side.
Re-run
```
./scripts/check-schema-drift.sh
```
if available.
Summarise which schema objects were brought back into sync.

当用户报告CI架构漂移故障时：

读取CI输出，确定实时/生成的架构、迁移或
```
db/schema.dbml
```
是否过时
将相关迁移或架构快照与
```
db/schema.dbml
```
进行比较
更新过时的一方
若可行，重新运行
```
./scripts/check-schema-drift.sh
```
总结哪些架构对象已恢复同步

Boundary With Feature Specs

与功能规范的边界

Use

db/schema.dbml

for structural persistence documentation. Use

specs/features/

for observable system behaviour.

Examples:

A
```
users.email
```
unique index belongs in
```
db/schema.dbml
```
.
The business rule explaining when a user may change their email belongs in
```
specs/features/
```
.
A foreign key from
```
orders.user_id
```
to
```
users.id
```
belongs in
```
db/schema.dbml
```
.
The checkout behaviour that creates an order belongs in
```
specs/features/
```
.

When both structure and behaviour change, update both files.

使用

db/schema.dbml

记录结构化持久化文档。使用

specs/features/

记录可观察的系统行为。

示例：

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

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

Completion Checklist

完成检查清单

Before finishing database documentation work, verify:

```
db/schema.dbml
```
exists when database schema docs are required.
Every touched table, column, FK, unique constraint, and index is represented.
DBML names match the real database names exactly.
Structural DB changes and DBML changes are included together.
Relevant behaviour changes are reflected in
```
specs/features/
```
when applicable.
```
./scripts/check-schema-drift.sh
```
was run if present and feasible.

完成数据库文档工作前，请验证：

当需要数据库架构文档时，
```
db/schema.dbml
```
已存在
所有涉及的表、列、外键、唯一约束和索引均已记录
DBML中的名称与实际数据库名称完全一致
数据库结构变更与DBML变更已同步完成
相关行为变更已在
```
specs/features/
```
中体现（如适用）
若存在且可行，已运行
```
./scripts/check-schema-drift.sh
```