#DBML #ER diagram #database diagram

DBML – Database Markup Language

郭彥廷 2021/07/20 15:00:00
29

 

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-one

l   'string'用於字串

body text [note: 'Content of the post']

l   欄位名稱或表格名稱可加上雙引號或不加

"start_date" DATE

l   '''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,代表postsusers是多對一的關係。

 

完整DBML語法介紹可參考DBML - Full Syntax Docs

 

Different from SQL DDL

DDL為實際創建、修改、刪除表格的語言,他的目的並非定義表格;

DBML則是陳述性的語言,也因此DBML著重在簡單書寫、閱讀及維護。 

 

由上可知,DDL必定會對應到某個特定的資料庫,可能是OraclePostgreSQL 或其他,

DBML則是database-agnostic的,沒有特別屬於哪種DB。因為DBML的撰寫是為了資料庫設計而非資料庫創建。

 

dbdiagram

dbdiagram.io是個免費的網站,幫助我們把DBML code轉換成視覺化的圖表。

可在左側編輯DBML code,右側圖表會跟著動態變化。

 

雙擊右側資料表中的某個欄位,左側編輯欄會定位到定義該欄位的DBML code

 

在右側圖表中的兩個欄位間拉線創造關聯,左側編輯欄也會隨之產出描述關聯的DBML code

 

dbdiagram上匯入SQL DDLER 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是用來設計資料庫而非創建資料庫。它簡潔、一致且具高可讀性。

要在SQLDBML間做轉換,可用它的CLI

要用DBML繪製ER diagram,可至dbdiagram.io

 

參考資料 :

https://www.dbml.org/home/

Github

https://github.com/holistics/dbml/

Community Contributions

 

 

郭彥廷