ChartDB 1.20.1 快速入门（导入 Schema 到生成 ER 图）

目标：从零走通 ChartDB 的核心工作流——把一个已有数据库的 Schema 导入 ChartDB 并生成可编辑的 ER（实体关系）图。本文以 MySQL 8.4.11 演示库（4 张表、3 条外键、9 个索引）为实测对象，Smart Query 返回的 JSON 完整通过合法性校验并成功导入，同时覆盖 SQL Script（DDL）与 DBML 两种导入方式及导出操作。已实测环境：ChartDB 1.20.1（http://localhost:18090）+ MySQL 8.4.11。

一、环境信息

ChartDB：1.20.1（自托管部署，访问地址 http://localhost:18090；部署方式见《ChartDB 1.20.1 Docker Compose 部署指南》）
演示数据库：MySQL 8.4.11，库名 demo，账号 root，密码 q1w2e3r4
演示库规模：4 张表（customers / products / orders / order_items），18 列，3 条外键，9 个索引
浏览器数据存储：IndexedDB（图表保存在浏览器本地，无需注册登录）

二、核心概念与工作原理

ChartDB 是纯前端 Web 应用：所有图表数据存储在你浏览器的 IndexedDB 里，服务端（nginx）只负责提供静态页面。它的工作流是「数据库 → JSON → 图表」：

ChartDB 生成一段针对目标数据库方言的 Smart Query（一条打包查询）；
你把这条查询放到自己的数据库里执行，得到一个 JSON 结果（描述库中所有表、列、主键、外键、索引、视图）；
把 JSON 粘贴回 ChartDB，它解析后在画布上渲染出 ER 图。

💡 技术拓展：把 Schema「搬进」可视化工具的主流方式对比——

方式原理优点缺点
Smart Query（ChartDB 采用）一条 SQL 查 information_schema 打包成 JSON 免装客户端、只要查询权限、结果即所需需要手动执行一次查询
全量逻辑备份解析（mysqldump/pg_dump → 解析 DDL）解析备份文件离线可得需要文件访问权，解析器要兼容各版本方言
直连抓取（DBeaver/Navicat）工具通过 JDBC/驱动直连枚举元数据一键全自动需要开放数据库端口给工具所在网络
连接探针 Agent（DrawSQL 等 SaaS）在数据库侧装只读代理云端自动同步需在库侧安装组件，有安全顾虑

ChartDB 选择 Smart Query 路线：不动数据库配置、不装任何组件、最小权限（只需 SELECT information_schema），这也是它「免账号、免直连」卖点的基础。

方式	原理	优点	缺点
Smart Query（ChartDB 采用）	一条 SQL 查 information_schema 打包成 JSON	免装客户端、只要查询权限、结果即所需	需要手动执行一次查询
全量逻辑备份解析（mysqldump/pg_dump → 解析 DDL）	解析备份文件	离线可得	需要文件访问权，解析器要兼容各版本方言
直连抓取（DBeaver/Navicat）	工具通过 JDBC/驱动直连枚举元数据	一键全自动	需要开放数据库端口给工具所在网络
连接探针 Agent（DrawSQL 等 SaaS）	在数据库侧装只读代理	云端自动同步	需在库侧安装组件，有安全顾虑

导入入口支持三种方式（新建图表时的对话框里切换）：Smart Query（支持全部 9 种方言）、SQL Script（直接粘贴建表 DDL，ClickHouse 与 Oracle 不支持）、DBML（粘贴 DBML 文本）。

三、准备工作

3.1 准备演示数据库

在 MySQL 中创建演示库与 4 张表（电商订单模型，含主键/外键/索引/注释，便于验证 ER 图的关系连线）。执行以下 DDL：

CREATE DATABASE IF NOT EXISTS demo;
USE demo;

CREATE TABLE customers (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '客户ID',
    name VARCHAR(100) NOT NULL COMMENT '客户姓名',
    email VARCHAR(200) NOT NULL COMMENT '邮箱',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY uk_customers_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客户表';

CREATE TABLE products (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '商品ID',
    title VARCHAR(200) NOT NULL COMMENT '商品名称',
    price DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '单价',
    stock INT NOT NULL DEFAULT 0 COMMENT '库存',
    PRIMARY KEY (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='商品表';

CREATE TABLE orders (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '订单ID',
    customer_id BIGINT UNSIGNED NOT NULL COMMENT '下单客户',
    status ENUM('pending','paid','shipped','done') NOT NULL DEFAULT 'pending' COMMENT '订单状态',
    amount DECIMAL(12,2) NOT NULL DEFAULT 0.00,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    KEY idx_orders_customer (customer_id),
    KEY idx_orders_status (status),
    CONSTRAINT fk_orders_customer FOREIGN KEY (customer_id) REFERENCES customers (id) ON UPDATE CASCADE ON DELETE RESTRICT
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单表';

CREATE TABLE order_items (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    order_id BIGINT UNSIGNED NOT NULL COMMENT '所属订单',
    product_id BIGINT UNSIGNED NOT NULL COMMENT '商品',
    quantity INT NOT NULL DEFAULT 1 COMMENT '数量',
    unit_price DECIMAL(10,2) NOT NULL COMMENT '成交单价',
    PRIMARY KEY (id),
    KEY idx_order_items_order (order_id),
    KEY idx_order_items_product (product_id),
    CONSTRAINT fk_items_order FOREIGN KEY (order_id) REFERENCES orders (id) ON DELETE CASCADE,
    CONSTRAINT fk_items_product FOREIGN KEY (product_id) REFERENCES products (id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单明细表';

验证建表结果：

mysql -uroot -pq1w2e3r4 -e "SHOW TABLES FROM demo;"

实测输出：

Tables_in_demo
customers
order_items
orders
products

3.2 打开 ChartDB 编辑器

浏览器访问 http://<服务器IP>:18090，首次打开出现语言选择对话框（可切换到简体中文），随后进入编辑器空画布。点击左上角 New 按钮新建数据库图表，进入「What is your Database?」数据库类型选择页，开始导入流程。

四、方式一：Smart Query 导入（推荐）

4.1 选择数据库类型

在「What is your Database?」选择页点选数据库类型 MySQL（支持 PostgreSQL、MySQL、SQL Server、MariaDB、SQLite、CockroachDB、ClickHouse、Oracle 等），编辑字段下拉选对应大版本（MySQL 8.x 默认即可），点击 Continue 进入「Import your Database」导入页。

4.2 复制 Smart Query

导入页顶部是方式切换按钮组：Smart Query / SQL Script / DBML，保持默认 Smart Query。页面展示一段为 MySQL 8 生成的打包查询（以 WITH fk_info as ( 开头，约 140 行，对应提示文案「Run this script in your database:」），点击查询文本框右上角的复制按钮取得完整查询。这条查询会从 information_schema 中把当前库的表、列、主键、外键、索引、视图一次性拼成 JSON。

⚠️ 注意：查询只读 information_schema，作用范围是当前连接的默认数据库（SQL 里的 DATABASE()），执行前先 USE 目标库; 或在客户端中选中目标库，否则结果为空。

4.3 在数据库中执行查询

把复制的查询放到 MySQL 客户端执行（本文用命令行演示，先选中 demo 库）：

mysql -uroot -pq1w2e3r4 demo -N < mysql8-smart-query.sql > smart-query-output.json

查询返回一行 JSON（实测 7909 字节），结构如下（输出节选，实测首段）：

{"fk_info": [{"schema":"demo","table":"orders","column":"customer_id","foreign_key_name":"fk_orders_customer","reference_schema":"demo","reference_table":"customers","reference_column":"id","fk_def":"FOREIGN KEY (customer_id) REFERENCES customers(id) ON UPDATE CASCADE ON DELETE RESTRICT"},{"schema":"demo","table":"order_items","column":"order_id","foreign_key_name":"fk_items_order",...

（输出节选，实测末段，comment 为中文表注释）

..."tables": [...,{"schema":"demo","table":"orders","rows":0, "type":"BASE TABLE","engine":"InnoDB","collation":"utf8mb4_0900_ai_ci","comment":"订单表"},{"schema":"demo","table":"order_items","rows":0, "type":"BASE TABLE","engine":"InnoDB","collation":"utf8mb4_0900_ai_ci","comment":"订单明细表"}], "views":[], "database_name": "demo", "version": "8.4.11"}

用 Python 校验 JSON 合法性与内容完整性（可选步骤，确认复制粘贴过程没有丢内容）：

python3 -c "
import json
d = json.loads(open('smart-query-output.json').read())
print('顶层键:', list(d.keys()))
print('tables:', len(d.get('tables',[])), 'fk_info:', len(d.get('fk_info',[])), 'pk_info:', len(d.get('pk_info',[])), 'columns:', len(d.get('columns',[])), 'indexes:', len(d.get('indexes',[])))
"

实测输出：

顶层键: ['fk_info', 'pk_info', 'columns', 'indexes', 'tables', 'views', 'database_name', 'version']
tables: 4 fk_info: 3 pk_info: 4 columns: 18 indexes: 9

4 张表、3 条外键、18 列、9 个索引全部在列，与建表 DDL 一致。

4.4 粘贴 JSON 并导入

回到 ChartDB 导入页，把整行 JSON 粘贴到结果输入框（占位文案「Script results here...」），点击 Import。导入成功后对话框关闭，画布上出现 4 张表卡片及连线。

4.5 认识生成的 ER 图

导入完成后画布内容：

每张表渲染为一张卡片：表头是表名与注释（如 customers 客户表），卡片体列出全部字段（图标区分主键 / 普通字段，字段行右侧显示类型与长度）；
表与表之间的连线表示外键关系：orders.customer_id → customers.id、order_items.order_id → orders.id、order_items.product_id → products.id，连线端点标注基数（1:n）；
点击画布空白处拖动平移，滚轮缩放，拖动表卡片调整布局；
右侧边栏按区块组织：Tables（表列表）、Refs（关系列表）、Dependencies、Custom Types、Visuals（Areas 区域 / Notes 便签）、DBML（当前图表的 DBML 文本）。

五、方式二：SQL Script（DDL）导入

没有条件在源库执行查询时（如只有建表脚本、只读备份），可直接粘贴 DDL。两种入口：继续用 4.1 节的导入流程，在导入页顶部按钮组切到 SQL Script；或后续随时从顶部菜单 Actions → Import → SQL 打开同样的对话框。把 3.1 节的 CREATE TABLE 语句（去掉 CREATE DATABASE/USE 两行）整段粘贴进输入框，点击导入即可，ChartDB 会解析 DDL 生成同样的表卡片与关系线。

适用范围与差异：

对比项	Smart Query	SQL Script（DDL）
输入来源	在目标库执行查询取回 JSON	任意现成的建表脚本
信息完整度	高（含注释、排序规则、索引基数、视图）	取决于脚本本身（无 COMMENT 就不显示注释）
支持方言	全部 9 种	除 ClickHouse、Oracle 外均支持
适用场景	生产库实时反向工程	只有 DDL 文件、离线设计稿

⚠️ 注意：DDL 导入按所选方言的解析器执行，跨方言脚本（如把 MySQL DDL 粘到 PostgreSQL 类型的图表）可能出现类型解析差异，导入前确认对话框顶部选对了数据库类型。

六、方式三：DBML 导入

DBML（Database Markup Language）是 ChartDB 的内部中间表示，右侧边栏 DBML 区块实时显示当前图表的 DBML 文本（可直接编辑，保存后反向更新画布）。从零开始导入：顶部菜单 Actions → Import → DBML（或 New 流程中把导入方式切到 DBML），粘贴如下文本（与演示库等价的最小示例）：

Table customers {
  id bigint [pk, increment]
  name varchar(100) [not null]
  email varchar(200) [not null, unique]
  created_at datetime [not null, default: `CURRENT_TIMESTAMP`]
}

Table orders {
  id bigint [pk, increment]
  customer_id bigint [not null]
  status varchar(20) [not null, default: 'pending']
  amount decimal(12,2) [not null, default: 0.00]
}

Ref: orders.customer_id > customers.id

粘贴导入后画布出现 2 张表与 1 条关系线。DBML 方式适合从 dbdiagram.io 等工具迁移设计稿，或手工快速起草新模型。

七、图表编辑基础

改表结构：点击表卡片上的字段行，右侧面板出现字段属性编辑器（名称、类型、可空、默认值、注释），改动即时同步到画布与 DBML 面板；
加字段：卡片底部点击「+」新增字段；
建关系：从一个字段的小圆点拖到目标表的目标字段，选择基数（1:1 / 1:n / n:m）后生成关系线；
删除对象：选中表/关系后按 Delete（或右键菜单删除）；
添加独立注释：工具栏选择便签（Note）元素，可钉在画布任意位置。

所有编辑只保存在浏览器 IndexedDB，建议重要图表定期导出（见第八节）。

八、导出

导出入口都在顶部菜单 Actions 下：Export SQL（子菜单选目标方言）与 Export as（子菜单：PNG / JPG / SVG / JSON）。

8.1 导出 SQL（跨方言迁移）

Actions → Export SQL：子菜单列出目标方言——当前图表方言（确定性转换，结果稳定）与 PostgreSQL、MySQL、SQL Server、MariaDB、SQLite（菜单项带 ✨ 标记的走 AI 生成）。未配 AI 时使用内置的确定性转换器（PostgreSQL→MySQL、PostgreSQL→SQL Server 有专门实现），点击 AI 方言项会提示需要配置 OpenAI key（或自建端点）。导出结果在对话框中展示，可复制或下载。

💡 技术拓展：ChartDB 的「AI 导出」与「确定性导出」——确定性导出是代码里写死的类型映射与语法转换规则，结果稳定可复现，目前覆盖 PostgreSQL→MySQL/SQL Server 两条路径；AI 导出把图表结构发给配置好的大模型（OPENAI_API_KEY 或自建端点）生成目标方言 DDL，覆盖任意组合但结果需人工校验。生产迁移建议两者结合：AI 生成 → 人工比对 → 试运行。

8.2 导出 DBML

当前图表的 DBML 实时显示在右侧边栏 DBML 区块，直接全选复制即可（ChartDB 未提供独立的 DBML 文件导出菜单项，DBML 文本即源文件），可作为版本库中的 Schema 设计源文件（文本 diff 友好）。

8.3 导出图片与 JSON

Actions → Export as：PNG（可调清晰度）、JPG、SVG 三种图片格式（底层基于 html-to-image 库渲染画布），另有 JSON 导出完整图表文件（含表/关系/区域/便签全部数据），JSON 文件可通过 Actions → Import → .json 重新导入，适合做备份与跨设备迁移。

💡 说明：JSON 导出/导入是官方的图表备份通道——ChartDB 数据存在浏览器 IndexedDB，清理浏览器数据会导致图表丢失，定期 Actions → Export as → JSON 并保存到文件系统是最简单的备份手段（自动化备份策略见进阶篇）。

九、常见问题（FAQ）

Q1：Smart Query 执行结果为空 JSON（tables 空数组）？ 查询的作用域是 DATABASE()（当前连接的默认库）。先 USE demo;（或客户端选中库）再执行；PostgreSQL 则需连对 database（每库独立），并在查询里确认 schema 过滤条件。

Q2：粘贴 JSON 后导入报错或只导入部分表？ 常见原因是复制时截断（JSON 是一整行超长文本）。先用 4.3 节的 Python 校验确认 JSON 完整合法；MySQL 还受 group_concat_max_len 限制，超大 schema 建议先执行 SET SESSION group_concat_max_len = 1000000; 再跑 Smart Query（MariaDB 官方脚本已内置该语句，实测值为 10000000）。

Q3：执行 Smart Query 需要什么权限？ 只需对 information_schema 的 SELECT 权限（所有用户默认可查自己有权限的库）；不写任何数据，不装组件。最低权限账号即可完成导入。

Q4：导入后表卡片重叠看不清？ ChartDB 有自动布局：右侧边栏或画布右键菜单中的「Arrange/自动排列」可一键重排；也可手动拖动卡片后用「区域（Area）」功能按业务域分组圈选。

Q5：换浏览器/换电脑图表不见了？ 数据在浏览器 IndexedDB 里。跨设备用导出 JSON/DBML → 新设备导入；同机清了浏览器数据同理。长期备份方案见《ChartDB 1.20.1 进阶实战与运维》篇。

十、参考链接

ChartDB 官方仓库：https://github.com/chartdb/chartdb
在线体验（官方云版）：https://app.chartdb.io
DBML 语法文档：https://dbml.dbdiagram.io/docs
相关文档：《ChartDB 1.20.1 Docker Compose 部署指南》《ChartDB 1.20.1 配置参数详解》《ChartDB 1.20.1 进阶实战与运维》