dbml

DBML：把数据库结构变成可版本化的代码

项目背景与痛点

数据库 schema 长期处于一种尴尬的位置：它是最重要的工程资产之一，却往往以最难协作的形式存在。SQL DDL 本身是给数据库引擎看的，可读性一般；各类 ERD 工具产出的又是二进制文件或云端画布，无法进入 Git 做 diff review；而 ORM 的模型定义（Prisma schema、Django models、Hibernate 注解）虽然文本化，却与具体语言和框架牢牢绑死。

结果是同一个 schema 存在三份副本：迁移脚本里一份、ERD 图里一份、文档里一份，彼此逐渐漂移。holistics/dbml 要解决的核心问题就是：用一种人类优先、数据库无关的 DSL 来描述 schema，让它像代码一样被评审、被版本控制、被工具消费。

DBML（Database Markup Language）的语法刻意做得比 DDL 短得多——一张表、几个字段、几条引用关系，几十行就能描述清楚。它不试图执行任何 SQL，只负责“定义与文档”，这一定位让它能站在所有数据库方言与 ORM 之上。

核心技术揭秘

从架构上看，DBML 工具链本质是一个双向的 schema 中间表示（IR）系统：文本进、模型出、方言再出。它由三层构成：解析层（parser/lexer）、语义层（Database 模型）、导出层（exporter/importer）。

解析层是项目最值得关注的部分。DBML 早期版本借助 Nearley 这类解析器生成器，用语法文件描述文法；随着 schema 规模增长，这种方式在解析速度与错误恢复上开始吃力，后续重写为手写解析器，换取更好的性能与更精确的报错定位（行列号 + 期望 token）。这是一个典型的“先求正确、再求快”的演进路径。

语义层把 AST 提升为统一的 Database 模型：Schema → Table → Field / Index / Ref / Enum / TableGroup / Note。这一层承担了大量隐式推断工作，例如根据 ref 两端字段的唯一性推断基数（一对一、一对多、多对多），处理复合主键、字段类型的大小写归一、跨 schema 引用的解析。这类“猜测语义”的逻辑往往是 bug 高发区，也是 DBML 与普通标记语言的关键区别。

导出层负责降维：把中间模型翻译成各数据库方言的 DDL，或者序列化成 JSON 供第三方工具消费。反向的 importer 则依赖 ANTLR 生成的分方言 SQL 语法，把存量 DDL 解析回中间模型——这条逆向链路难度远高于正向导出，因为真实世界的 SQL 充斥着方言扩展、注释怪癖与非标准写法。

整个工程的复杂度集中在一个点上：如何用一套不依赖具体数据库的模型，容纳所有数据库的差异。 DBML 的答案是“只建模公共子集 + 用 Note 兜底”，这既是它的优雅，也是它的天花板。

功能亮点与差异

对比 Mermaid 的 erDiagram、PlantUML、SchemaSpy 或 Prisma schema，DBML 的差异化优势有三：

其一，语言中立且工具链完整。它既是文本格式，又配套 CLI（dbml2sql / sql2dbml）、解析库与渲染生态。你可以把它当作 schema 的“源代码”，而 ERD 只是它的可视化产物之一。

其二，文档能力内建。Note、TableGroup、StickyNote 让它不只是结构定义，还能承载业务语义与布局信息——这让 schema 文档不再需要额外维护一份 Confluence 页面。

其三，反向导入。把遗留系统的 DDL 一次性转成 DBML，再纳入版本管理，这是很多团队落地的第一步，也是竞品普遍缺失的能力。

应用场景与落地建议

适合的场景：中大型团队需要一处 schema 单一事实源；需要跨库（MySQL + PostgreSQL 并存）统一描述；需要在 PR 中 review 结构变更；以及生成对外交付的数据库文档。

注意事项要讲清楚：DBML 导出的 SQL 是结构快照，不是迁移脚本——它不会生成 ALTER TABLE，别指望用它替代 Flyway/Liquibase。此外，分区、触发器、存储过程、权限、字符集排序规则等数据库特性大多无法表达，只能落到备注里。超大 schema（数百张表）建议按域拆成多个 .dbml 文件再合并，避免单文件解析与渲染成为瓶颈。

综合评价

优点：语法学习成本极低，半小时上手；中间模型设计干净，作为 IR 有二次开发价值；双向转换与文档能力实用；采用 MIT 宽松许可，集成风险小；社区活跃，已被 dbdiagram.io 等产品长期验证。

不足：表达能力被“跨库公共子集”的定位锁死，遇到数据库专有特性只能妥协；可视化能力依赖商业产品，自托管场景需要自行接渲染；语法仍在演进，早期版本存在解析性能与错误提示粗糙的历史包袱；生态重心偏向 Holistics 自家产品，第三方工具链不算繁荣。

一句话总结：DBML 不是数据库工具，而是 schema 的编程语言。如果你的痛点是“schema 没法像代码一样协作”，它值得立刻引入；如果你期待它替代迁移框架或完整覆盖数据库能力，那会失望。