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

◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください
【6/19開催】Kong Community Japan Meetup #4
本イベントでは、Kong Inc. のVP of ProductであるReza Shafii氏もプレゼンターとして参加。当社からはアーキテクト マネージャーの槌野の登壇が決定!参加無料です!!
https://column.api-ecosystem.sios.jp/connect/kong/1081/

【6/21開催】開発者目線でのSBOMとの向き合い方
SBOMの導入から開発者がSBOMの作成・管理を自動で行っていくための方法(デモ)を紹介します。SBOMを全く知らない人から、開発との統合までを紹介するので様々なレベルの方に学びがあるライブとなる予定です!
https://tech-lab.connpass.com/event/321422/

【7/19開催】現場で役立つAzure神小技10+α 〜生成AI,RAG,コスト削減など旬な技術満載のLT大会〜
Azureの最新技術や実用的な小技を紹介する特別なライトニングトーク大会を開催します!
https://tech-lab.connpass.com/event/319077/

【7/26開催】最適なIaCツールを選ぼう
プロジェクトでのツール選びに困らないための重要な観点をご説明します!
https://tech-lab.connpass.com/event/319532/

こんにちは!サイオステクノロジーの安藤 浩です。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

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

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 に記載されています。

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

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

アバター画像
About 安藤浩 2 Articles
2023年10月にサイオステクノロジーに入社。主にバックエンド側のWebアプリ(C#, Python, Typescript)開発を経験。趣味は家庭菜園。

ご覧いただきありがとうございます! この投稿はお役に立ちましたか?

役に立った 役に立たなかった

2人がこの投稿は役に立ったと言っています。


ご覧いただきありがとうございます。
ブログの最新情報はSNSでも発信しております。
ぜひTwitterのフォロー&Facebookページにいいねをお願い致します!



>> 雑誌等の執筆依頼を受付しております。
   ご希望の方はお気軽にお問い合わせください!

Be the first to comment

Leave a Reply

Your email address will not be published.


*


質問はこちら 閉じる