DBML – Database Markup Language
Overview
DBML (Database Markup Language)是一個開源的領域特定語言(DSL)，用以定義及記載資料庫的schema及結構。
本文將簡略介紹DBML的語法並示範用相關工具產生資料表關聯圖及在SQL檔與DBML檔間做轉換。
Why DBML
DBML的產生是為了解決開發者進入龐大且複雜的專案時，因為現存的ER diagram已經過時、未更新，DDL code又難以閱讀，
導致沒辦法一窺專案資料庫結構全貌的挫折。
另外，有些時候我們因為某些因素而不在資料庫使用foreign keys時，我們用工具產出的database diagram會因此沒有代表表格間關係的連接線 。
此時，如果是用底下介紹的dbdiagram.io網站繪製database diagram，則我們可以很直覺的在不同表格間的欄位拉線表示關聯。
Syntax
以下為簡易的DBML範例：
Table users {
id integer
username varchar
role varchar
created_at timestamp
}
Table posts {
id integer [primary key]
title varchar
body text [note: 'Content of the post']
user_id integer
status post_status
created_at timestamp
}
Enum post_status {
draft
published
private [note: 'visible via URL only']
}
Ref: posts.user_id > users.id // many-to-one
可看出DBML的寫法相當得淺顯易懂。
DBML的幾個符號規則如下
l {}：用於indexes, constraints和定義table
l []：設定用
id integer [primary key]l //：註解用
Ref: posts.user_id > users.id // many-to-onel 'string'：用於字串
body text [note: 'Content of the post']l 欄位名稱或表格名稱可加上雙引號或不加
"start_date" DATEl '''multi-line string'''：用於多行字串
Project DBML {
Note: '''
# DBML - Database Markup Language
DBML (database markup language) is a simple, readable DSL language designed to define database structures.
## Benefits
* It is simple, flexible and highly human-readable
* It is database agnostic, focusing on the essential database structure definition without worrying about the detailed syntaxes of each database
* Comes with a free, simple database visualiser at [dbdiagram.io](http://dbdiagram.io)
'''
}
l
`：用於function
default: `now() - interval '5 days'`
關聯的部分，DBML以很直覺式的大於、小於及dash符號書寫。
//3 Relationship Types
// < one-to-many
// > many-to-one
// - one-to-one如前面範例的Ref: posts.user_id > users.id，代表posts對users是多對一的關係。
完整DBML語法介紹可參考DBML - Full Syntax Docs
Different from SQL DDL
DDL為實際創建、修改、刪除表格的語言，他的目的並非定義表格；
DBML則是陳述性的語言，也因此DBML著重在簡單書寫、閱讀及維護。
由上可知，DDL必定會對應到某個特定的資料庫，可能是Oracle、PostgreSQL 或其他，
DBML則是database-agnostic的，沒有特別屬於哪種DB。因為DBML的撰寫是為了資料庫設計而非資料庫創建。
dbdiagram
dbdiagram.io是個免費的網站，幫助我們把DBML code轉換成視覺化的圖表。
可在左側編輯DBML code，右側圖表會跟著動態變化。
雙擊右側資料表中的某個欄位，左側編輯欄會定位到定義該欄位的DBML code；
在右側圖表中的兩個欄位間拉線創造關聯，左側編輯欄也會隨之產出描述關聯的DBML code。
在dbdiagram上匯入SQL DDL產ER diagram
Step 1. 選擇import匯入sql檔
Step 2.可選貼入sql語句或直接上傳sql檔
Step 3.送出後，就會在左側產出轉譯後的DBML code，右側則為database diagram。
如要分享給他人，可選(1) Export to PDF 或 (2) Share分享連結
Command-line Tool (CLI)
DBML有可用的command-line tool幫助我們在SQL檔及DBML檔間做轉換。
可用npm或是yarn下載。
下載指令如下：
npm install -g @dbml/cli
# or if you're using yarn
yarn global add @dbml/cli
l 將SQL檔轉換為DBML檔
Syntax如下：
$ sql2dbml <path-to-sql-file>
[--mysql|--postgres]
[-o|--out-file <output-filepath>]
如沒加上SQL檔資料庫型別的選項，則預設為PostgreSQL
要產出成檔案需加--out-file 或 -o，沒加則會直接印出DBML code。
產檔成功則會如圖中顯示文字：Generated DBML file from SQL file
l 將DBML檔轉換為SQL檔
Syntax如下：
$ dbml2sql <path-to-dbml-file>
[--mysql|--postgres]
[-o|--out-file <output-filepath>]資料庫選項一樣預設為PostgreSQL；沒加--out-file 或 -o則直接印出SQL
產檔成功則會如圖中顯示文字：Generated SQL dump file
In a nutshell
DBML是用來設計資料庫而非創建資料庫。它簡潔、一致且具高可讀性。
要在SQL及DBML間做轉換，可用它的CLI；
要用DBML繪製ER diagram，可至dbdiagram.io。
參考資料 :
Github
https://github.com/holistics/dbml/
Community Contributions
- Emacs Mode for DBML by ccod
- Vim Plugin for DBML by jidn
- VSCode Plugin for DBML by duynvu
- Python parser for DBML by Vanderhoof
- FloorPlan: Android's Room to DBML by julioz
- Go parser for DBML by duythinht
- DbmlForDjango: Converter between Django models.py and DBML
- parseServerSchema2dbml: Converter between ParseServer MongoDB _SCHEMA collection and DBML by stepanic
- dbml-renderer: A DBML CLI renderer
