本文提到的工具
邊閱讀邊在瀏覽器中開啟工具,立即試試整個流程。
「這張表到底連到哪裡去了?」
「這個 user_id 參照的是哪張表?」「咦,這張表該不會沒有被任何地方參照吧?」——光靠閱讀原始 SQL 來追蹤關聯,就像在腦中拼拼圖一樣。
SQL to ER 圖轉換工具 接收 CREATE TABLE 語句後,能立即把資料表、欄位、主鍵、外鍵渲染成 Mermaid ER 圖。所有處理都在瀏覽器內完成,SQL 不會外流。

這篇文章要說明 DDL 解析器實際上是怎麼運作的,以及因為這種運作方式,您應該知道哪些涵蓋範圍上的限制。
使用方法
CREATE TABLE users (
id BIGINT PRIMARY KEY,
name VARCHAR(255) NOT NULL
);
CREATE TABLE orders (
id BIGINT PRIMARY KEY,
user_id BIGINT NOT NULL,
total_amount INTEGER NOT NULL,
FOREIGN KEY (user_id) REFERENCES users(id)
);
貼上這段之後,會得到以下 Mermaid erDiagram 程式碼:
erDiagram
users {
BIGINT id PK
VARCHAR name
}
orders {
BIGINT id PK
BIGINT user_id
INTEGER total_amount
}
orders }|--|| users : "user_id -> id"
把產生的程式碼直接貼到 GitHub README 或 Pull Request,就會自動渲染出來。
解析器的原理:用正規表示式拆解 DDL
這個工具沒有使用完整的 SQL 解析函式庫,而是採用以正規表示式為基礎的輕量解析器(SqlParser.parseDdl),分三個階段處理。
第一步:移除註解並拆分語句
const cleanSql = sql
.replace(/--.*$/gm, '') // 移除單行註解
.replace(/\/\*[\s\S]*?\*\//g, '') // 移除區塊註解
.trim();
const statements = cleanSql.split(';').map(s => s.trim()).filter(Boolean);
由於語句是單純以 ; 拆分,若預設值中含有分號的 DDL 就無法正確解析——不過這種情況在實務上幾乎不會發生。
第二步:只在括號外的逗號處拆分欄位定義
如果單純用 , 拆分 CREATE TABLE 的內容,像 DECIMAL(10, 2) 這種型別定義裡的逗號也會被誤判為分隔符。因此解析器會追蹤括號的深度,只有在深度為 0 時的逗號才視為分隔符。
private static splitByCommaOutsideParens(text: string): string[] {
let depth = 0;
// 遇到 '(' depth++,遇到 ')' depth--,只有 depth === 0 時的逗號才是分隔符
for (let i = 0; i < text.length; i++) {
if (text[i] === '(') depth++;
else if (text[i] === ')') depth--;
if (text[i] === ',' && depth === 0) { /* 在此拆分 */ }
}
}
這和 JSON⇔CSV 轉換工具 的 CSV 解析器用的是同一套思路——逐字元掃描並維護狀態。SQL 的欄位定義和加引號的 CSV 欄位表面上不同,但都有「分隔符在特定情況下會失效」這個共通特性。
第三步:把每一行分類成 PRIMARY KEY、FOREIGN KEY 或欄位定義
拆分後的每一行都會用正規表示式比對,歸類成三種之一。
// 資料表層級的主鍵,也支援像 PRIMARY KEY (id, tenant_id) 這樣的複合主鍵
const pkMatch = trimmed.match(/PRIMARY KEY\s*\(([\s\w,`"]+)\)/i);
// 資料表層級的外鍵
const fkMatch = trimmed.match(
/FOREIGN KEY\s*\(([\s\w`"]+)\)\s*REFERENCES\s*(?:['\`"]?(\w+)['\`"]?\.)?['\`"]?(\w+)['\`"]?\s*\(([\s\w`"]+)\)/i
);
// 欄位定義,也會擷取欄位定義結尾內嵌的 REFERENCES 子句
const colMatch = trimmed.match(/^['`"]?(\w+)['`"]?\s+(\w+(?:\([\w\s,]+\))?)(.*)$/i);
REFERENCES 的正規表示式同時能比對欄位定義結尾的內嵌外鍵,以及資料表層級的 FOREIGN KEY 子句。也支援複合主鍵——像 PRIMARY KEY (id, tenant_id) 這樣的定義,會讓兩個欄位都標上 PK。
輸出結果:烏鴉腳表示法
這個工具產生的關聯行採用烏鴉腳表示法:
orders }|--|| users : "user_id -> id"
箭頭從 }|(多)指向 ||(一),代表「多筆訂單屬於同一位使用者」的一對多關係。若想完整了解這套表示法,包括一對一、多對多,以及識別/非識別關聯的差異,可參考 Mermaid ER 圖語法完全參考。
要留意的是,Mermaid 的 erDiagram 語法不允許欄位型別包含括號,因此長度規格會被自動移除——VARCHAR(255) 會變成 VARCHAR(type.replace(/\([^)]*\)/g, ''))。
解析器不支援的 DDL 寫法
由於採用以正規表示式為基礎的輕量解析器,而非完整的 SQL 語法解析——這是為了控制程式體積、讓瀏覽器能快速執行所做的刻意取捨——因此有以下限制:
| 寫法 | 支援狀況 |
|---|---|
CREATE TABLE 內的 PRIMARY KEY/FOREIGN KEY(資料表層級與欄位層級皆可) |
✅ 支援 |
複合主鍵 PRIMARY KEY (a, b) |
✅ 支援 |
ALTER TABLE ... ADD [CONSTRAINT ...] FOREIGN KEY / ADD PRIMARY KEY(pg_dump 的輸出格式) |
✅ 支援 |
CREATE TABLE IF NOT EXISTS |
✅ 支援 |
加上 schema 前綴的 schema.table_name |
✅ 支援(僅擷取資料表名稱部分) |
-- 單行註解//* */ 區塊註解 |
✅ 解析前會先移除 |
有些遷移工具與 pg_dump 會用另一條 ALTER TABLE 語句事後加上外鍵(Rails 的 ActiveRecord 就是常見例子)。新增外鍵或主鍵的 ALTER TABLE 會被讀入,並反映在關聯與鍵上。新增、修改欄位等其他 ALTER TABLE 則不會反映。
檢視產生的圖表時的檢查重點
- 每張資料表是否都設定了主鍵
- 外鍵的方向是否符合預期
- 有沒有沒被任何地方參照的孤立資料表
- 中介表是否正確表達了多對多關係
在 Pull Request 審查時,附上 ER 圖遠比只看 SQL diff 更能清楚傳達異動的影響範圍。由於輸出是純文字(Mermaid),可以直接貼進審查留言中。
手動調整圖的配置
自動排版的圖,資料表一多就變得難讀。在 SQL 轉 ER 圖中貼上 CREATE TABLE 語句並按「繪製 ER 圖」,資料表與外部鍵連線會自動排好,並以可拖曳資料表的圖顯示。
- 連線會避開其他資料表,以直角繪製。 從外部鍵欄位那一列出發,進入被參照欄位那一列
- 線端使用雞爪表示法:外部鍵一側為「多」,被參照一側為「1」,允許 NULL 的欄位會有圓圈
- 可就地編輯:邊看圖邊修改資料表名稱、欄位(名稱・型別・PK・NOT NULL・UNIQUE)與關聯線
- 「Mermaid」分頁仍可像以前一樣查看 Mermaid 程式碼與圖片。編輯圖之後,Mermaid 也會同步反映
- 支援匯出 PNG / SVG / JSON 與複製 CREATE TABLE 語句。先存成 JSON,結構改變時就能載入並修改
讓圖好讀的訣竅有三個:父(主檔)放左、子(交易)放右;多對多的中間表放在兩個父表之間;資料表很多時,依功能拆成多張圖,各自存成 JSON。Mermaid 輸出不包含位置資訊。
結構比較、檢查、範例資料,以及 SQL Server 輸出
除了畫圖之外,SQL to ER 圖轉換工具還能利用貼上的 CREATE TABLE 做到以下事情:
- 比較兩個結構(遷移 SQL):貼上舊的與新的
CREATE TABLE,就會依資料表、欄位、型別、可否為 NULL、DEFAULT、主鍵與外鍵的差異產生ALTER TABLE(建立 → 新增・變更 → 外鍵 → 刪除的順序)。支援 PostgreSQL、MySQL、SQLite 與 SQL Server。刪除欄位或資料表(資料會消失),以及執行前建議確認的語句(新增沒有DEFAULT的NOT NULL、型別變更、主鍵變更、需要約束名稱的操作、SQLite 無法做到的變更)都會附上標記與原因。也會從「刪除加新增」的組合,警告可能是重新命名的欄位與資料表(遷移會刪除後重建,若其實是改名,資料就會消失) - 結構檢查:指出沒有主鍵的資料表、名為
xxx_id卻沒有外鍵的欄位、沒有索引的外鍵欄位、snake_case與camelCase混用、超過 30 個欄位的資料表,以及沒有長度的VARCHAR - 索引建議:產生外鍵欄位用的
CREATE INDEX,避免刪除父資料列或聯結時掃描整張表 - 範例資料:產生遵守外鍵的
INSERT(父資料表在前、主鍵為流水號、符合欄位名稱與型別的值、可用 seed 重現、1~100 列) - SQL Server 輸出:方言選項中有 SQL Server。型別會變成
INT、NVARCHAR、BIT、DATETIME2、UNIQUEIDENTIFIER,識別字用[方括號],自動遞增變成IDENTITY(1,1),SQL Server 沒有的RESTRICT則改為NO ACTION
這些都只讀取 SQL 定義。不會連線到資料庫,也看不到您的資料。 執行前請務必確認結果。
常見問題
可以用在 MySQL 或 PostgreSQL 的 DDL 嗎?
以 CREATE TABLE 為主的一般 DDL 都適用。方言特有的型別或選項(例如 ENGINE=InnoDB)會直接被忽略,不影響資料表、欄位、鍵值的擷取。
沒有外鍵的 SQL 也能畫出圖嗎?
可以,會顯示為資料表與欄位的列表。不過關聯線是根據 FOREIGN KEY/REFERENCES 的資訊繪製的,若想清楚呈現關聯,請在 DDL 中加入這些定義。
用 ALTER TABLE 加上的外鍵會被辨識嗎?
會。ALTER TABLE ... ADD FOREIGN KEY 與 ADD PRIMARY KEY(也可加上 ADD CONSTRAINT 名稱)會被讀入,並反映在關聯與主鍵上。新增、修改欄位等其他 ALTER TABLE 則不會反映。
產生的圖可以貼到文件裡嗎?
可以。由於是以 Mermaid 格式輸出,貼到 GitHub README 或設計文件中,就能以貼近程式碼的方式管理架構圖。烏鴉腳表示法的讀法可參考 Mermaid ER 圖語法完全參考。
可以自己移動資料表的位置嗎?
可以。在「圖(可編輯)」分頁拖曳資料表即可。可用方向鍵微調,也支援復原與重做。「自動排列」可回到初始配置。
能從兩個結構的差異自動產生 ALTER TABLE 嗎?
可以。但它只比較定義,所以無法判斷資料會怎麼樣。刪除欄位或資料表會標示「資料會消失」,新增沒有 DEFAULT 的 NOT NULL 或變更型別會標示「執行前確認」。只是改名的欄位會顯示為刪除加新增,因此會警告可能是改名的組合。執行前請務必確認語句內容。
也能匯出成 DBML 與 PlantUML
在 ER 圖編輯區下方,「複製 DDL」旁邊還有 「複製 DBML」「複製 PlantUML」 按鈕。DBML 可以直接貼到 dbdiagram.io,PlantUML 則可貼到 PlantUML 編輯器或文件工具中。
Table orders {
id INT [pk]
customer_id INT [not null]
}
Ref: orders.customer_id > customers.id [delete: cascade]
- DBML:欄位設定有
pk、increment、not null、unique、default,關聯寫成Ref: 子表.欄位 > 父表.欄位(一對一為-)。複合主鍵不會在每個欄位加pk,而是寫在indexes區塊 - PlantUML:以
entity繪製資料表,主鍵加上*與<<PK>>並放在分隔線上方。關聯是父表 ||--o{ 子表(外鍵允許 NULL 時為|o--o{) - 外鍵的
ON DELETE/ON UPDATE會從 DDL 讀入,並反映在 DDL 匯出與 DBML 的[delete: …, update: …]中
總結
- 解析採用以正規表示式為基礎的輕量實作,關鍵在於只在括號外的逗號處拆分
- 支援 PRIMARY KEY、FOREIGN KEY(資料表與欄位層級皆可),以及複合主鍵
- 透過
ALTER TABLE事後加上的外鍵與主鍵受支援;新增、修改欄位等其他ALTER TABLE不會反映 - 產生的程式碼採用 Mermaid 的烏鴉腳表示法,讀法可參考另一篇參考文章
把手邊的 SQL 交給這個工具,找出那些您可能一直沒注意到的資料表關聯吧。
