Classi開発者ブログ

教育プラットフォーム「Classi」を開発・運営するClassi株式会社の開発者ブログです。

GitHub ActionsとSchemaSpyを活用したデータベースドキュメント自動生成とGitHub Pagesへの公開方法

CI/CD 開発者体験

こんにちは、kobitoチームのアインです。この記事では、最近チームで導入したデータベースのドキュメント自動生成の仕組みとその経緯について紹介します。

なぜ自動化しようと思ったか

サービスを運用する上で、データベースのドキュメント管理は重要な業務の一つです。データベースのスキーマが変更される度に、ドキュメントを手作業で更新する必要があります。しかし、このような手動更新には以下の課題があります。

  • 記録漏れや実際のデータベースとの乖離が生じやすい
  • 複数人が同時に開発すると、ドキュメントと実際のデータベースの状態に差が生じやすい

これらの課題を解決するため、GitHub Actionsを活用したドキュメント自動生成の仕組みを導入しました。これにより、データベースの変更があるたびに最新かつ正確なドキュメントが自動的に生成されます。さらに、生成されたドキュメントをGitHub Pagesでホスティングすることで、社内メンバーはいつでも簡単に最新のデータベースドキュメントを参照でき、コミュニケーションの円滑化にもつながります。その結果、開発者はドキュメント管理の作業負担を減らし、本質的な開発業務やユーザーへの価値提供に集中できるようになります。

なお、GitHub Pages を社内限定公開に設定できるのは GitHub Enterprise のみのため、導入時には注意してください。

データベースドキュメントの自動生成にはSchemaSpy を使用しています。

SchemaSpy について

SchemaSpy（スキーマスパイ）は、データベースのスキーマを解析し、自動的に詳細なドキュメントや図表をHTML形式で生成するオープンソースツールです。

SchemaSpyが生成するドキュメントには、テーブルの一覧、テーブル間のリレーション、各テーブルの詳細な構造情報（カラム、インデックスなど）が含まれており、視覚的に把握しやすくなっています。 実際に生成されるドキュメントの例として、EpiViruSurfデータベースのドキュメントをご覧ください。

データベースドキュメントホームページを例として

SchemaSpyをローカル環境で実行する方法

1.準備

本手順は、PostgreSQLデータベースを使用していること、およびSchemaSpyが正常に動作しているデータベース環境に対して適用することを前提としています。 データベースのドキュメントを自動生成するためには、まず対象となるデータベースの接続情報を設定する必要があります。 この接続情報はファイルまたはコマンドライン引数で指定できますが、今回は設定ファイルを使用して指定します。

データベースの接続情報（ホスト名、ポート番号、データベース名、ユーザー名、パスワードなど）を設定ファイル（schemaspy.properties）に記述します

# データベースのタイプ（例：PostgreSQL）
schemaspy.t=pgsql11
# JDBCドライバへのパス（任意)
schemaspy.dp=drivers
schemaspy.host=localhost
schemaspy.port=5432
schemaspy.db=database
schemaspy.u=postgres
schemaspy.p=password
# ドキュメント生成後のファイルを出力するフォルダ
schemaspy.o=output
# ドキュメント作成対象のスキーマ名（例：public）
schemaspy.s=public

また、ドキュメントが出力されるフォルダ（output）をあらかじめ作成しておく必要があります。

2. データベースドキュメントの生成

Dockerを利用してドキュメントを生成します。以下のコマンドで実行できます。

docker run \
  -v "[path-to-output-folder]:/output" \
  --net="host" \
  -v "[path-to-config-file]:/schemaspy.properties" \
  schemaspy/schemaspy:snapshot

詳細な使い方や最新情報については、SchemaSpyの公式ドキュメント を参照してください。 生成されたドキュメントは ./output/ ディレクトリに出力されます。 ( 出力先は設定ファイルで変更可能 )。生成されたドキュメントをローカルで確認するには./output/ ディレクトリのindex.htmlをブラウザで開くことができます

GitHub Actionsを使ってSchemaSpyを自動実行・デプロイする際の注意点

今回作成したデータベースドキュメントを社内メンバーがいつでも参照できるように、GitHub Pagesへのデプロイを行います。デプロイには、GitHub Actionsを使った方法を紹介します。なお、GitHub Pagesへの初期設定の手順については、以下の記事で詳しく紹介していますので、参照してください。

docs.github.com

データベースが使用可能な状態であることを事前に確認する

GitHub Actionsのワークフローでデータベースを起動すると、データベースが完全に使用可能な状態になるまでには少し時間がかかります。このため、データベースがまだ使用可能でない状態でSchemaSpyを実行するとエラーが発生し、ドキュメントを正常に生成できません。そのため、Dockerのヘルスチェック機能を利用して、データベースが使用可能な状態であることを事前に確認する必要があります。 具体的には、以下のオプションを設定します。

  • --health-cmd pg_isready
    • PostgreSQLの起動確認
  • --health-interval 10s
    • 10秒間隔で起動状態を確認

この方法により、データベースが確実に使用可能な状態になってからドキュメントの生成を開始できるため、エラーを回避できます。

権限が不足して出力先のファイルを生成できない

ワークフロー上でデータベースドキュメントを生成する際、SchemaSpyは出力先となるフォルダがあらかじめ存在し、十分な権限が付与されていることを要求します。 具体的には、書き込み権限（write）と実行権限（execute）を事前に付与する必要があります。

また、GitHub Actionsを使ってGitHub Pagesへデプロイする際にも、そのフォルダに対して読み取り権限（read）が必要です。

つまり、ワークフロー内でデータベースドキュメントを生成する際、GitHub Actions上のUbuntu環境で動作するSchemaSpyが、出力フォルダに対して十分なファイル操作を行えるようにするため、以下のLinuxファイルシステム上の権限を事前に設定する必要があります。

  • 読み取り権限（read）
    • フォルダ内のファイルをGitHub Actionsが読み取れるようにする
  • 書き込み権限（write）
    • SchemaSpyがドキュメントを生成し、ファイルを作成・編集できるようにする
  • 実行権限（execute）
    • フォルダへのアクセスおよびディレクトリ内へのファイル書き込みを許可する

これらを適切に設定することで、ワークフローでのデータベースドキュメント生成およびGitHub Pagesへのデプロイがスムーズに行えます。

実際のGitHub Actionsワークフロー例

ここまで、データベースドキュメントを自動生成する際の注意点について説明してきました。 では実際に、それらの設定をどのようにGitHub Actionsのワークフローに落とし込んでいくのかを見ていきましょう。

以下は、main ブランチに変更が push されるたびに、SchemaSpy を使ってデータベースのドキュメントを生成し、GitHub Pages に自動デプロイする例です。

name: Generate DB docs with SchemaSpy and Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  generate-and-deploy-db-docs:
    services:
      postgres:
        image: postgres:14
        ports:
          - "5432:5432"
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      # setup
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Prepare a directory for SchemaSpy output
        run: mkdir -m 777 output

      # db migration
      # ...省略

      # generate
      - name: Run SchemaSpy to generate ERD
        run: |
          docker run \
            -v "${GITHUB_WORKSPACE}/output:/output" \
            --net="host" \
            -v "${GITHUB_WORKSPACE}/db/schemaspy.properties:/schemaspy.properties" \
            schemaspy/schemaspy:snapshot

      # publish
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./output
      - uses: actions/deploy-pages@v4

GitHub Pages へのデプロイが完了すると https://<OWNER>.github.io/<REPOSITORY> から データベースドキュメントを閲覧できるようになります。

まとめ

今回はチームで導入した、データベーススキーマからドキュメントを自動生成する仕組みについて、その経緯を紹介しました。特別な方法ではありませんが、自動化されたことで、より良いドキュメントを作るために設計や説明文にも力を入れる意識が高まりました。

もしデータベースドキュメントの管理や自動生成のためのツール選定に迷っている方がいれば、ぜひ一度この方法を試してみてください

© 2020 Classi Corp.