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

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

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

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

前提

まず、以下の前提のローカル環境を用意し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 に記載されています。

テーブル構造のプレビュー

Table Structure のタブでテーブル構造を確認することができます。

リレーションシップのプレビュー

Relationshipsのタブでdbdiagram.io でプレビューしたようなER図を確認することができます。

まとめ

DBMLファイルの作成・プレビュー、Github actions でCIを実行することでdbdocs.io でDBMLファイルのプレビューをすることができました。コードベースでDBのドキュメント管理が楽になりそうです。

参考URL

https://github.com/holistics/dbml

https://dbml.dbdiagram.io/docs

https://dbdocs.io/docs

https://dbdocs.io/docs/ci-integration

https://dbdocs.io/docs/project-access-control