dbml-kit

DBML 数据模型管理工具集。提供 DBML 文件的校验、渲染、比较、迁移、检查、同步、报告、文档生成等功能。

安装

npm（推荐）

npm install -g dbml-kit

注意：sync 和 compare 命令需要额外安装 @dbml/cli：

npm install -g @dbml/cli

独立二进制（无需 Node.js）

从 GitHub Releases 下载对应平台的二进制文件：

| 平台 | 文件 | 大小 | |------|------|------| | Linux x64 | dbml-kit-linux-x64 | ~38MB | | Linux ARM64 | dbml-kit-linux-arm64 | ~37MB | | Windows x64 | dbml-kit-windows-x64.exe | ~112MB | | Windows ARM64 | dbml-kit-windows-arm64.exe | ~109MB |

# Linux/macOS
chmod +x dbml-kit-linux-x64
./dbml-kit-linux-x64 --help

# Windows
dbml-kit-windows-x64.exe --help

限制：独立二进制不支持 sync 和 compare 命令（需要数据库驱动）。如需这些功能请使用 npm 安装。

命令列表

| 命令 | 说明 | |------|------| | validate <file> | 校验 DBML 文件语法 | | render <file> | 将 DBML 渲染为 ER 图（SVG/DOT） | | lint <file> | 检查 DBML 最佳实践 | | diff <base> <target> | 比较两个 DBML 文件的结构差异 | | migrate <base> <target> | 生成数据库迁移 SQL 脚本 | | check <base> <target> | 检查 schema 变更的兼容性 | | sync | 从数据库逆向生成 DBML 文件 | | compare <local-file> | 对比数据库与本地 DBML 文件的差异 | | history <file> | 追溯 DBML 文件在 Git 历史中的变更记录 | | report <base> <target> | 生成变更报告 | | doc <file> | 生成数据字典文档 | | edit <file> | 在浏览器中编辑 DBML 文件 |

使用示例

校验 DBML

dbml-kit validate schema.dbml
dbml-kit validate schema.dbml --format json

渲染 ER 图

dbml-kit render schema.dbml                    # 输出 SVG
dbml-kit render schema.dbml --format dot        # 输出 DOT
dbml-kit render schema.dbml -o er-diagram.svg   # 指定输出文件

比较差异

dbml-kit diff old.dbml new.dbml                 # 文本输出
dbml-kit diff old.dbml new.dbml --format json   # JSON 输出
dbml-kit diff old.dbml new.dbml --format md     # Markdown 输出

生成迁移 SQL

dbml-kit migrate old.dbml new.dbml -d postgres -o upgrade.sql
dbml-kit migrate old.dbml new.dbml -d postgres --dry   # 预览 SQL

检查变更兼容性

dbml-kit check old.dbml new.dbml               # 默认 text 格式
dbml-kit check old.dbml new.dbml --strict      # 将警告视为阻断
dbml-kit check old.dbml new.dbml --format json

从数据库同步 DBML

# 使用连接字符串
dbml-kit sync --url 'postgresql://user:pass@localhost:5432/mydb?schemas=public' --out schema.dbml

# 使用独立参数
dbml-kit sync --host localhost --port 5432 --database mydb --user myuser --password mypass --out schema.dbml

# 兼容国产 PG 数据库（磐维/瀚高/人大金仓/openGauss）
dbml-kit sync --host 10.1.193.181 --port 37700 --database uampdb --schema uamp --user uamp --pg-compat

对比数据库与本地文件

dbml-kit compare schema.dbml --url 'postgresql://user:pass@localhost:5432/mydb'
dbml-kit compare schema.dbml --host localhost --database mydb --user myuser --password mypass

生成变更报告

dbml-kit report old.dbml new.dbml --format md
dbml-kit report old.dbml new.dbml --format html --output report.html

生成数据字典

dbml-kit doc schema.dbml --format md
dbml-kit doc schema.dbml --format html --output docs.html

在浏览器中编辑

dbml-kit edit schema.dbml          # 默认端口 3000
dbml-kit edit schema.dbml -p 8080  # 指定端口

Lint 配置

创建 .dbml-lint.yml 文件自定义 lint 规则：

rules:
  naming:
    table: snake_case
    column: snake_case
  required:
    table_note: false
    column_note: false
    primary_key: true
  types:
    discourage: [text, int]
    severity: warning
  indexes:
    foreign_key_index: warning

使用配置：

dbml-kit lint schema.dbml --config .dbml-lint.yml

开发

npm install
npm run build:all    # 构建 CLI + CodeMirror
npm run dev          # 开发模式
npm test             # 运行测试

许可证

MIT