liam

Liam：把 ER 图从"事后补画"变成"自动化产物"

项目背景与痛点

数据库 schema 的文档化，一直是团队协作里那笔没人愿意承认的隐形债。表结构散落在 migration 文件、ORM 模型和 DBA 的口头约定中；新人接手一个几十张表的老库，第一件事往往是打开 dbdiagram.io 手工画图，或者对着 pgAdmin 一张表一张表地双击。真正的麻烦在于：图一旦画出来，就开始过时。schema 加了一列、改了外键，图不会自己更新，几个月后它反而成了错误信息的来源。

传统方案有三条路：手工画图，好看但不可维护；SchemaSpy / pgAdmin 自动生成，可维护但页面难看，没人愿意点第二次；DBML / dbdiagram 这类 DSL，需要额外维护一份定义文件，又多了一个会过时的源头。Liam 押注的是第四条路：直接以数据库 schema 本身作为唯一可信来源，自动产出既好看又可信的 ER 图，并把它接进 PR 流程里。

核心技术揭秘

Liam 的定位是“schema 可视化引擎”，不是画图 GUI。这决定了它的架构是典型的解析 → 建模 → 布局 → 渲染四段流水线，全部用 TypeScript 实现，并以 monorepo 拆成 db-structure、erd-core、cli 等独立包，方便被其他工具复用。

关键取舍有两个。第一，解析层不依赖数据库连接。Liam 主要面对 PostgreSQL，做法是直接对 DDL / schema 导出文件做静态解析：它把 PostgreSQL 官方的解析器（libpg_query 系）接入运行时，拿到真正的 AST，而不是用正则去“猜”表定义。这保证了 CREATE TABLE、ALTER TABLE、COMMENT ON、CREATE TYPE 等语法的准确性，也避开了“要不要连生产库”这个安全问题。第二，布局交给算法。ER 图的难点从来不是画框，而是自动排版：几十张表、上百条外键，节点重叠和连线交叉会让图彻底不可读。Liam 使用 ELK.js 的 layered 布局，以外键方向作为分层约束，再配合局部优化，这也是它“看起来像人画的”的主要原因。

渲染层基于 React Flow（XYFlow），意味着图是 DOM 而非静态 SVG 快照：节点可拖拽、可聚焦、可高亮上下游链路——代价是表规模很大时会遇到明显的性能上限。

功能亮点与差异

最值得说的不是“自动生成”，而是 PR 级别的 schema 变更可视化。Liam 提供 GitHub App 与 CLI，能在 pull request 里贴出“这次改了哪些表、加了哪些列、新增了哪条外键”的图对比。把 schema diff 从文本 diff 变成图 diff，这件事 dbdiagram 和 SchemaSpy 都没有认真做，而对做 code review 的团队来说，它的价值远大于一张漂亮的静态图。

其次是单表聚焦与关联链路高亮。真实项目里没人能一眼看完 200 张表，Liam 支持按表聚焦、沿外键展开上下游，比“全量大图”更贴近日常使用。

第三是可嵌入。erd-core 是独立包，理论上可以塞进自己的后台管理系统或文档站，做一个“实时 schema 视图”——这是纯粹的 SaaS 画图工具给不了的。

应用场景与落地建议

适合：中大型 PostgreSQL 项目的 schema 文档化；需要 review migration 的团队；接手遗留系统时的快速摸底。

生产使用要注意几点。其一，解析质量取决于你提供的 schema 文件是否完整——只给一张表的 DDL，图就只有一张表；\d+ 导出顺序、分区表、继承表这些边界情况要提前验证。其二，大库性能：几百张表以上，交互式渲染会明显变卡，建议按业务域拆成多个入口图，而不是硬扛全量。其三，别把 Liam 当 schema 的“守护者”——它只做可视化，不做约束校验与漂移检测，真正的唯一可信来源还得是 migration 工具。

综合评价

优点：设计边界清晰，"解析"与"展示"解耦得干净；布局质量在开源方案里属于第一梯队；PR 集成这个切入点非常务实；TypeScript 全栈，二次开发门槛低。

缺点：PostgreSQL 之外的数据库支持明显偏弱，MySQL / SQLite 的解析能力不在同一水平；生态年轻，API 稳定性还在打磨期；重度依赖 React Flow 的 DOM 渲染，超大 schema 场景需要用户自己想办法降低复杂度。

一句话：如果你要的是“能自己更新、review 时能看、同事不会嫌弃”的 ER 图方案，Liam 目前是开源里最接近答案的那个；但如果你的项目横跨多种数据库，或者要求图能稳定嵌进大型系统，建议先做个 POC 再决定。