DB設計書の更新を自動化してみた #Laravel

1. はじめに

業務ではDB設計書をエクセルで記載することが多いのですが、ドキュメントが更新されずに実装と異なることを課題に感じていました。DB設計に使用できるツールを探しているときにdbdocsというツールを見つけました。
dbdocsではCLIが用意されているため、GitHub Actionsで自動化できると考えました。この記事ではDB設計書をdbdocsで作成し、GitHub Actionsを使って自動更新する手順を紹介したいと思います。

2. 対象読者

DB設計ツールを探している方
実装と乖離しないDB設計書を模索している方
Laravelを使っている方

4. dbdocsについて

dbdocsではDBMLを使用してスキーマを定義します。定義したDBMLからWebベースのドキュメントを作成することができます。基本的な機能は無料で使うことができます。詳細についてはリンクからご確認ください！

dbdocsではデモサイトが用意されていますので、是非触ってみてください！
画像はデモサイトのキャプチャです。

5. 環境

本記事ではLaravelプロジェクトを前提にしています。
composer.json及びpackage.jsonです。各ファイルの一部は省略しています。

composer.json



{
    "require": {
        "php": "^8.1",
        "guzzlehttp/guzzle": "^7.2",
        "laravel/framework": "^10.10",
        "laravel/sanctum": "^3.3",
        "laravel/tinker": "^2.8"
    },
    "require-dev": {
        "aphisitworachorch/kacher": "dev-master",
        "fakerphp/faker": "^1.9.1",
        "laravel/pint": "^1.0",
        "laravel/sail": "^1.18",
        "mockery/mockery": "^1.4.4",
        "nunomaduro/collision": "^7.0",
        "phpunit/phpunit": "^10.1",
        "spatie/laravel-ignition": "^2.0"
    },
}

package.json

{
    "devDependencies": {
        "axios": "^1.1.2",
        "laravel-vite-plugin": "^0.8.0",
        "vite": "^4.0.0"
    },
    "dependencies": {
        "dbdocs": "^0.8.4"
    }
}

6. 手順

6-1. DBMLの出力

まずはdbdocsで使用するためのDBMLファイルを生成します。
ここではaphisitworachorch/kacherを使って出力します。

$ composer require --dev aphisitworachorch/kacher:dev-master
$ php artisan dbml:parse

コマンド実行によりstorage/app/dbml直下にDBMLファイルが出力されます。
(出力内容はDBML形式であるがファイルの拡張子は.txtになっています)

6-2. dbdocsの初期設定

次に、出力したDBMLファイルを使ってdbdocsの初期設定を行います。
手順は公式サイトのドキュメントに沿って進めます。

$ npm install dbdocs
$ npx dbdocs login
# 入力したメールアドレスへOPTコードが送信されるので、コードを入力する

$ npx dbdocs build <DBMLファイルのパス> --project=<プロジェクト名>
# プロジェクト名は任意の名前で大丈夫です

最後のコマンドが成功すると、生成されたdbdocsプロジェクトのURLが表示されます。
そのURLにアクセスするとDBMLファイルに基づいたドキュメントが生成されていることが確認できます。

dbdocsの無料プランではURLが公開されているため、パスワードを設定することを推奨します。

$ npx dbdocs password --set <パスワード> --project <プロジェクト名>

6-3.dbdocsのトークン発行

dbdocsのトークンを使用することでメールアドレスによるログインなしに更新することができます。トークンの発行は下記のコマンドを実行します。

$ dbdocs token -g

発行されたトークンはLaravelプロジェクト直下の.envファイルに下記の環境変数で定義します。

DBDOCS_TOKEN=<発行されたトークン>

6-4. GitHub Actionsのyamlファイル作成

最後に、GitHub Actionsのyamlを作成します。
下記はdatabase/migration以下が更新されるとdbdocsを更新する例です。
コード内容の解説は割愛しますが、dbdocs周りはコメントで補足しています。

name: dbdocs CI

on:
  push:
    branches:
      - main
    paths:
      - "database/migrations/**"

jobs:
  setup:
    runs-on: ubuntu-latest

    services:
      db:
        image: mysql:8.0
        ports:
          - 3306:3306
        env:
          MYSQL_ROOT_PASSWORD: root
          MYSQL_DATABASE: dbdocs
    env:
      DB_CONNECTION: mysql
      DB_HOST: 127.0.0.1
      DB_PORT: 3306
      DB_DATABASE: dbdocs
      DB_USERNAME: root
      DB_PASSWORD: root

    steps:
      - uses: actions/checkout@v2
      - name: cache vendor
        id: cache
        uses: actions/cache@v1
        with:
          path: ./vendor
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            ${{ runner.os }}-composer-

      - name: copy .env.example
        run: cp .env.example .env
      - name: composer install
        if: steps.cache.outputs.cache-hit != 'true'
        run: composer install -n --prefer-dist
      - name: migrate
        run: php artisan migrate

        # dbdocsのCLIパッケージをインストールします
      - name: install dbdocs
        run: npm install -g dbdocs
        # 正常にパッケージがインストールできたか確認します
      - name: Check dbdocs
        run: dbdocs
        # dbmlファイルを生成します。
      - name: create dbml file
        run: php artisan dbml:parse
        # 生成されたファイル名は毎回異なるため、dbdocs.dbmlというファイル名にリネームします
      - name: rename dbml file
        run:  mv storage/app/dbml/`ls storage/app/dbml/` storage/app/dbml/dbdocs.dbml
        # 生成されたdbmlファイルでdbdocsを更新します
      - name: update dbdocs
        run: dbdocs build ./storage/app/dbml/dbdocs.dbml --project=<プロジェクト名>

このCIにより、Laravelプロジェクトでmigrationファイルが更新されるたびにdbdocsが自動更新されて、ドキュメントと実装が乖離する課題を解決することができます！

7. さいごに

dbdocsは無料プランでも十分使えると思っています！
有料プランに入るとテーブルをグループ化したり、テーブルヘッダー色を変更できたり、ドキュメントとしての見やすさは向上するかと思います。しかし、有料プランの月60ドルは辛いので現状入る予定はないかなと思っています。有料プランの機能が増えたら、課金も検討したいと思います！

DB設計書の更新を自動化してみた