DSL 語法

.dbschema 是一種一看就懂的資料庫結構寫法：一行一個欄位，關聯單獨宣告。寫好之後在工作區貼上，或在 VS Code 打開，就會畫出關聯圖。

快速開始

兩張表加一條外鍵關聯，就是一張最小的關聯圖。複製下面這段，到工作區按「匯入」貼上試試。

dbschema

table Users {
  PK Id    bigint        not null
     Email nvarchar(255) not null "登入 Email"
}

table Orders {
  PK Id     bigint not null
  FK UserId bigint not null
}

relation FK_Orders_Users {
  Orders.UserId N -> 1 Users.Id
}

重點只有三個：table 宣告資料表、每行一個欄位、relation 宣告關聯。// 之後是註解。

資料表

table 名稱 "說明" { … }。名稱前面可以加 schema（sales.Orders），省略時是 dbo；說明字串可有可無，會顯示在卡片標題旁。名稱大小寫有別，關鍵字不分大小寫。

dbschema

table Users "系統使用者" {
  PK Id bigint not null "使用者 ID"
}

// 帶 schema 的寫法；省略時是 dbo
table sales.Orders {
  PK Id bigint not null
}

欄位

格式是 [標記] 名稱型別 [null | not null] [default 值] ["備註"]，一行一個。欄位對齊只是為了好讀，空白數量不影響。

dbschema

table Products {
  PK  Id        bigint         not null "商品 ID"
  UQ  Sku       nvarchar(64)   not null
      Name      nvarchar(200)  not null
      Price     decimal(18,2)  not null default 0
      Note      nvarchar(4000) null     "備註"
      IsActive  bit            not null default 1
}

標記

標記	意思
`PK`	主鍵，隱含 not null
`FK`	外鍵標記；只是視覺標記，關聯要用 relation 宣告
`UQ`	唯一
`IDX`	有索引的標記；真正的索引用 index 語句

規則

情況	怎麼解讀
可以同時有好幾個標記	PK UQ Id bigint
沒寫 null / not null	預設可為空（PK 例外）
型別一個參數	長度，例如 nvarchar(255)
型別兩個參數	精度與小數位，例如 decimal(18,2)
行尾的字串	欄位備註，會直接顯示在卡片上
default	數字、字串或識別字，例如 default 0、default "draft"

群組

群組是你自己定的功能分類（例如「訂單」「會員」），跟資料庫的 schema 是兩回事，可以跨 schema。同一群組的表會排在一起、用同一個顏色，工具列也可以只看某個群組。

dbschema

// 一、集中宣告並列出成員
group Identity "身分與權限" {
  Users
  Roles
}

// 二、描述集中宣告，成員標在各自的 table 上
group Sales "訂單與金流"

table Orders in Sales {
  PK Id bigint not null
}

一張表只能屬於一個群組。table X in G 而 G 沒宣告時，會自動當成一個沒有說明的群組。

索引

索引獨立宣告；複合索引照你列的順序保存。外鍵欄位沒有索引時，工作區會給一個建議（不影響圖表）。

dbschema

index IX_Posts_Author_CreatedAt on Posts(AuthorId, CreatedAt)
unique index UX_Users_Email on Users(Email)

關聯

箭頭左邊是持有外鍵的一方，右邊是被參照的一方：Posts.AuthorId N -> 1 Users.Id 讀作「很多篇 Posts 對到一個 User」。這個方向也決定了聚焦時的「上游／下游」。

dbschema

relation FK_Posts_Users {
  Posts.AuthorId N -> 1 Users.Id
}

// 複合外鍵
relation FK_OrderLines_Orders {
  OrderLines.(OrderId, TenantId) N -> 1 Orders.(Id, TenantId)
}

寫法	意思
`N -> 1`	多對一（最常見：箭頭左邊持有外鍵）
`1 -> N`	一對多
`1 -> 1`	一對一
`N -> M`	多對多

欄位上的 FK 標記不會自動產生關聯；圖上的線一律來自 relation。

其他格式

SQL

工作區的「匯入 → SQL」可以直接貼 CREATE TABLE，支援 MySQL、SQL Server、PostgreSQL、SQLite。欄位上的 REFERENCES 和表層級的 FOREIGN KEY 都會變成關聯；匯入後存成 DSL。VS Code 裡用「DBSchema: Import SQL as .dbschema」。

sql

CREATE TABLE users (
  id    bigint PRIMARY KEY,
  email text NOT NULL
);

CREATE TABLE orders (
  id      bigint PRIMARY KEY,
  user_id bigint NOT NULL REFERENCES users(id)
);

Markdown

檔名用 .schema.md，把 DSL 放在語言標成 dbschema 的程式碼區塊裡，文件跟結構可以寫在同一份。

markdown

# 訂單模組

```dbschema
table Orders {
  PK Id bigint not null
}
```

JSON

檔名用 .schema.json。這是工作區「匯出」產生的完整結構，適合給程式讀寫或備份。

快捷鍵

網頁版跟 VS Code 插件通用，標「網頁版」的只有網頁版有。

按鍵	做什麼
`Ctrl / Cmd + F`	搜尋資料表或欄位
`Ctrl / Cmd + 滾輪`	縮放畫布
`拖曳背景`	平移畫布（移動模式）／框選（選取模式）
`單擊表名`	聚焦：相關的表亮起，其餘淡化；再點一次取消
`單擊欄位`	欄位級聚焦：只亮該欄位與對應的外鍵欄位
`雙擊表或欄位`	跳回 DSL 裡的定義
`Tab`	用鍵盤一張一張走到資料表
`Enter／空白鍵`	聚焦目前這張表（再按一次取消）
`Shift + Enter`	跳回這張表的定義
`Esc`	取消聚焦、關閉對話框
`Ctrl / Cmd + 點表`	多選（網頁版），Delete 刪除選取的表
`Delete`	刪除點選的表或多選的表，提示上可以復原（網頁版）
`Ctrl / Cmd + A`	全選畫面上的資料表（網頁版）
`Ctrl / Cmd + Z`	復原上一步編輯（網頁版）
`Ctrl / Cmd + Shift + Z、Ctrl + Y`	重做（網頁版）
`Ctrl / Cmd + D`	複製出一份選取或聚焦的表（網頁版）
`Ctrl / Cmd + C`	把選取或聚焦的表的 DSL 定義複製到剪貼簿（網頁版）
`+ / -`	放大／縮小畫布
`Shift + 1`	縮放到看得到整張圖

錯誤與建議

SCHEMA_* 是會讓圖畫不正確的錯誤，LINT_* 只是設計上的建議。解析錯誤不會讓整份檔案失敗：看得懂的部分照樣畫出來，看不懂的那行列在問題清單裡，並標出行與列。

代碼	意思與處理
`SCHEMA_PARSE_ERROR`	這一行看不懂。訊息會標出行:列，通常是少了括號、多了符號或關鍵字拼錯。
`SCHEMA_DUPLICATE_TABLE / COLUMN / INDEX`	同名的表、欄位或索引宣告了兩次。
`SCHEMA_UNKNOWN_TABLE / COLUMN`	關聯、索引或群組指到不存在的表或欄位，檢查大小寫（Users ≠ users）。
`SCHEMA_RELATION_SOURCE_NOT_FOUND / TARGET_NOT_FOUND`	關聯箭頭兩邊有一邊找不到。
`SCHEMA_INVALID_CARDINALITY`	基數只能寫 1、N、M。
`SCHEMA_INVALID_COMPOSITE_RELATION`	同一個 relation 區塊裡的每一行都要指向同一組來源／目標表。
`SCHEMA_DUPLICATE_GROUP / CONFLICTING_GROUP`	群組宣告了兩次，或一張表被放進兩個群組。
`LINT_FK_NO_INDEX`	建議：外鍵欄位沒有索引，JOIN 可能比較慢。不影響圖表。
`LINT_NO_PK`	建議：這張表沒有主鍵。
`LINT_EMPTY_TABLE`	建議：這張表一個欄位都沒有。
`LINT_NAMING / LINT_TYPE_SUFFIX`	建議：命名風格不一致。