DB設計書の管理が楽になるDBML入門 – DBMLの書き方,dbdiagram.io, dbdocs の紹介 –

こんにちは！サイオステクノロジーの安藤浩です。DB設計書の生成が容易にできるDBMLをご紹介します。DBMLの入門として、DBMLの書き方、ER図生成方法、Github actionsでCIを実行して閲覧する方法をご紹介させていただきます。

1 DBMLとは
2 DBMLの書き方
- 2.1 テーブルの書き方
- 2.2 リレーションシップの書き方
3 Github actionsでCIを実行し、dbdocs.io で閲覧
4 まとめ
5 参考URL

DBMLとは

DBML は DataBase Markup Language の略でDB構造を定義するために設計された言語です。

DB構造に焦点を当てており、可読性の高い言語です。 dbdiagram.io や dbdocs.io などを利用することでDBドキュメントの生成が可能です。

コードベースで図を生成できる点でPlantUMLと似ていますね。

DBMLの書き方

テーブルの書き方

まずはテーブルの定義の例をもとにDBMLの記法を紹介していきます。users というテーブルを作成してみます。コードは以下のようになります。

Table users {
  id integer [pk]
  first_name varchar
  last_name varchar
  email varchar [not null]
  password varchar [note: 'Hashed password']
  created_at datetime [not null, default: `now()`]
  updated_at datetime
 
  Indexes {
    email [unique, name: "ui_users_email"]
  }
  Note: 'table: users'
}

上記のテーブル定義を dbdiagram.io の左側のコード記載部分に張り付けると右側にプレビューが表示されます。

以下は dbdiagram.io でのプレビューをした時の表示です。(Noteの箇所は説明のため加工しています)

(1) Table {テーブル名} でテーブルを定義します。

(2) {カラム名} {データ型} [{設定}] という書き方でカラムを定義します。id の箇所の[pk] はプライマリキーを示しています。{設定}の箇所には以下の属性が記載できます。カンマ区切りで複数可能です。

pk または primary key : プライマリキー
unique : ユニークキー
null または not null : Null 許容かNull 非許容
default : デフォルト値
increment : オートインクリメント
note : メタデータとしてのメモ

(3) 特定のカラムにメモを書けます。dbdiagram.io ではカラムにフォーカスが当たるとメモが表示されます。

(4) デフォルト値を設定することができます。

(5)インデックスの定義方法です。name に付けたいインデックス名を記載することでインデックスが作成されます。Noteはテーブルのメモとして記載できます。ここでもdbdiagram.io ではテーブル名の箇所にフォーカスが当たるとメモとインデックスが表示されます。

リレーションシップの書き方

さらに上記に倣い、profiles というテーブルを定義してみます。

Table profiles as prof {
  id integer [pk]
  user_id integer
  bio varchar
  website varchar
  email varchar
  created_at datetime [not null, default: `now()`]
  updated_at datetime
  Indexes {
    user_id [unique, name: "idx_profiles_user_id"]
  }
}

Table {テーブル名} as {エイリアス名}でエイリアス名が利用できます。

users と profiles に1対1のリレーションシップを作成したい場合は以下のように記載します。

Ref fk_profiles_user_id_users_id : profiles.user_id - users.id

このように記載することで以下のように外部キーを作成することができます。

1対1の場合は-でリレーションシップを作成します。

もう一つ articles テーブルを作成して多対1のリレーションシップも作成してみます。

Enum articles_status_enum {
  draft
  published
  private
  deleted
}


Table articles {
  id integer [pk]
  title varchar
  content text [note: 'Content of the article']
  user_id integer
  status articles_status_enum
  created_at datetime [not null, default: `now()`]
  updated_at datetime
  Indexes {
    user_id [name: "idx_articles_user_id"]
  }
  Note: 'table: articles'
}


Ref "fk_articles_user_id_users_id" : articles.user_id > users.id

ここで articles テーブルの status カラムはEnum というユーザ指定の値を設定できるようにしています。

末尾のRef の箇所で多対1のリレーションシップをarticles と usersで作成しています。

<: 1対多 ( 例:users. < articles.user_id )
>: 多対1 ( 例:articles.user_id > users.id )
-: 1対1 ( 例:users.id - profiles.user_id )
<>: 多対多 ( 例:shops.id <> products.id )

このようにDBMLからER図を生成することができます。

上記ではdbdiagram.io でプレビューしましたが、VsCode拡張機能の DBML Live Preview や DBML Entity-Relationship Diagrams visualizer を利用することでVsCode上でもプレビューすることができます。また、 vscode-dbml を利用することでSyntax HighlightingやSQLへの出力が可能になります。SQLへの出力については npm パッケージ: @dbml/cli も利用できます。

Github actionsでCIを実行し、dbdocs.io で閲覧

ここからは Github Action を利用して、dbdocs.io 上でテーブル構造とER図を閲覧する方法を紹介します。

前提

まず、以下の前提のローカル環境を用意しdbdocs のアクセストークンを生成します。

node.js version: v20.12.2
npm version: 10.5.0

dbdocs のインストール＆アクセストークン生成

以下のコマンドを実行し、dbdocs をインストールします。ここでのdbdocs のバージョンは0.9.2です。

npm install dbdocs

npx dbdocs login

でログインし、dbdocs のアクセストークンを生成します。

npx dbdocs token -g

ここで生成されたアクセストークンを Github actions のシークレット DBDOCS_TOKEN として保存しておきます。

また、dbdiagram.io で作成していたDBMLをファイルとして保存しておきます。ここでは ./project/blogsample.dbml に保存します。保存したファイルの最上部に以下のように記載して、dbdocs.io 上で閲覧できるように事前にプロジェクトの情報を記載しておきます。

Project BlogSample_MYSQL {
  database_type: 'MySQL'
  Note: '''
    # BlogSample (MySQL)
    **References** :
    https://dbdocs.io/docs
    https://dbml.dbdiagram.io/home
  '''
}

Github actionsのワークフロー記述

Github actionsのワークフローに以下のように記載します。ここでもう一つGithub actionsのシークレット DBDOCS_PASSWORD_BLOGSAMPLE を設定し、dbdocs.io 上のドキュメントへのアクセスの際にパスワードをかけておきます。(パスワードを設定しないとパスワードなしで公開状態になります)

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]


jobs:
  build-with-dbdocs:
    runs-on: ubuntu-22.04


    steps:
      - uses: actions/checkout@v4
      - name: Install dbdocs
        run: sudo npm install -g dbdocs


      - name: Check dbdocs
        run: dbdocs


      - name: Update dbdocs project
        env:
          DBDOCS_TOKEN: ${{ secrets.DBDOCS_TOKEN }}
        run: dbdocs build ./project/blogsample.dbml --password ${{ secrets.DBDOCS_PASSWORD_BLOGSAMPLE }}

有料版であれば招待された人のみが閲覧できるPrivateなプロジェクトが設定できます。詳しくは https://dbdocs.io/docs/project-access-control に記載されています。