开发者如何用 dbdiagram.io 的 DSL 快速绘制数据库关系图

dbdiagram.io 是一个用文本 DSL（DBML）描述数据库结构、再自动渲染成关系图的在线工具。它适合需要快速把表结构画出来、导出 SQL 或分享给团队评审的开发者。核心工作流是：在左侧写 DBML 定义表和字段，右侧实时生成图，用 ref 声明外键后自动出现连线，最后导出或分享。下面按这个顺序说明具体做法和容易卡住的地方。

用 DBML 定义表、字段与主键

DBML 的基本单位是 Table，字段写在花括号里，每行一个。主键用 [pk] 标注，自增用 [increment]，非空用 [not null]，注释用 //。

Table users {
  id integer [pk, increment]
  email varchar [not null, unique]
  created_at timestamp
}

Table orders {
  id integer [pk, increment]
  user_id integer
  total decimal
  status varchar
}

输入这段后，右侧会立刻出现两张表。字段类型是自由文本，工具不会校验它是否匹配某个具体数据库，所以写 integer、int、bigint 都能画出来，但导出 SQL 时会按你写的原样输出——这一点在需要精确 DDL 时要留意。

用 ref 声明外键，让连线自动生成

关系图的价值在于表之间的连线。DBML 用 ref 表达外键，写法有两种：

// 方式一：单独一行声明
Ref: orders.user_id > users.id

// 方式二：写在字段行内
Table orders {
  id integer [pk]
  user_id integer [ref: > users.id]
}

> 表示多对一（orders 的多个 user_id 指向一个 users.id），- 表示一对一，<> 表示多对多。声明后右侧两张表之间会自动出现连线，端点落在对应字段上。

关系线不显示时，先查这三处：

• 引用的表名或字段名拼写不一致（DBML 区分大小写）。
• ref 写在了表定义之外但表名写错，工具不会报错，只是静默不画线。
• 字段被写在 Table 花括号之外，等于没定义，自然没有连线端点。

调整布局、分组与配色

图变复杂后，可读性靠三件事：

• 分组：用 TableGroup 把相关表圈在一起，例如把 users、orders、order_items 放进 TableGroup ecommerce { ... }，图上会出现一个带标题的边框。
• 配色：在表定义后加 [headercolor: #3498DB] 之类的属性，给表头换色，用来区分模块（如用户域、订单域）。
• 布局：拖拽表的位置，连线会自动跟随。布局调整通常保存在当前图的会话里，刷新后是否保留取决于图是否已保存到你的账户。

导出 SQL、PNG 或分享链接

画完后按用途选出口：

分享链接是这类在线工具最省事的协作方式，评审时对方能直接看到最新结构，不用来回传截图。

常见语法报错排查

DBML 报错通常集中在几类：

• 缺少逗号或括号不匹配：字段属性写在 [] 里，多个属性用逗号分隔，如 [pk, not null]。
• 表名重复：同一张图里不能有两个同名 Table。
• ref 指向不存在的字段：先确认被引用的表和字段都已定义，且拼写一致。
• 注释符号用错：DBML 用 // 单行注释，/* */ 多行注释，用 # 不会生效。

遇到报错时，右侧通常会给出出错行号，从那一行往上检查最近的括号和逗号即可。

什么时候适合用它

如果你的目标是快速把已有或计划中的表结构可视化、导出建表脚本、发给团队看，dbdiagram.io 的文本驱动方式比拖拽式工具更快，改字段只需改一行文本，图自动更新。如果需求是反向工程（从现有数据库自动生成图）或需要严格的数据库方言校验，则要确认工具是否支持你的具体场景，必要时配合其他工具使用。