GitLab PagesでER図(SchemaSpy)

やりたい事と経緯

• 既存データベースのER図を共有したい。
• 実データベースからスキーマ情報・ER図を起こすにはSchemaSpyというのがあり、使ってみたら便利。
• GitLab CI/CDによりGitLab PagesとしてWebページを作ればプロジェクトメンバー限定で公開できて便利。

SchemaSpyの使い方

2022/12現在Qiitaには7件掲載。

じゃあ、実際の開発では頻繁にスキーマ変更して共有したいか？というとそんなんでもないし(開発内容・フェーズにもよりますが)、手で変換してどっかに共有すれば良い気もするが、それは何処に置くのか問題と、乖離していく問題があり…。ということで、とりあえずGitLab Pagesにしてみる。

サンプル gitlab-ci.yml

あくまでもテスト的に用意したものでキャッシュなどは活用していないです。実際のCIの流れの中ではビルドやユニットテスト等のための環境をCI実行環境内に構築し、その際に持ってきたライブラリー等をキャッシュし、それを各フェーズで使い回すことになると思います。簡略化とSchemaSpyの動作確認なので、今回Railsですがそこら辺は省いてます(具体的にはbundle installでのGem)。
また、現実ではrules.changesなどでスキーマの元になる情報が変更された場合に実行するなどが必要になりますね。

SchemaSpyはDockerコンテナーで動かしておらず、Java環境を用意し実行しています。CIの中でdocker runするのが良いかもしれませんが、その場合docker:dindをサービスとして動かしたりDocker CLIの準備も必要なので、Java環境で直接実行する方が効率的だと考え、こちらを選びました。

• データベース:
  • PostgreSQL用にしている
  • MySQL等他のデータベースの場合は次の変更が必要
    • services:のサービスコンテナー変更
    • JDBCドライバーの変更
    • 当然、接続情報の変更
• 言語・フレームワーク・スキーマ管理ツール
  • Ruby on Rails の Active Record をマイグレーションツールとして使っている
  • 他の言語・フレームワーク・スキーマ管理ツールを利用する場合は、コメントにあるRails部分などを変えれば良いと思う
• 他のドキュメント
  • 実際の場合MarkdownやAsciiDocなどで他のドキュメントをテキストとして記述し、それらと合わせ今回のER図やAPIドキュメントなど自動生成されるドキュメンを合体させると思う
  • docsの下に置いたAsciiDocと混ぜてPagesにすることにしている
  • Markdownやサイトジェネレーターなどを使う場合はそこら辺の考慮が必要

.gitlab-ci.yml

variables:
  DOCKER_HOST: tcp://docker:2375

erd:
  stage: build
  image: ruby:3.0.4
  services:
    - postgres:13.9-alpine
  variables:
    # PostgreSQL service environments
    POSTGRES_USER: username
    POSTGRES_PASSWORD: password
    POSTGRES_DB: example
    POSTGRES_HOST: postgres
    POSTGRES_PORT: 5432
    POSTGRES_HOST_AUTH_METHOD: trust
    # SchemaSpy + JDBC driver versions
    SCHEMASPY_VERSION: 6.1.0
    POSTGRESQL_JDBC_VERSION: 42.5.1
  before_script:
    # データベースクライアントとSchemaSpyを動作させるためのJava環境を準備。
    - apt-get update -qq && apt-get install -y postgresql-client-13 openjdk-11-jre-headless
    # ここはRailsとしての準備とデータベースへのスキーマ設定。他の言語・フレームワーク・マイグレーションツールを使うならその手法に置き換える。
    - export DATABASE_URL="postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}"
    - bin/bundle install
    - bin/rails db:create db:schema:load
    # SchemaSpyとJDBCドライバーの準備。他のデータベース利用ならそちらを。
    - curl -o schemaspy.jar -L https://github.com/schemaspy/schemaspy/releases/download/v${SCHEMASPY_VERSION}/schemaspy-${SCHEMASPY_VERSION}.jar
    - curl -OL https://jdbc.postgresql.org/download/postgresql-${POSTGRESQL_JDBC_VERSION}.jar
  script:
    - mkdir -p docs/schemaspy
    # 接続情報をオプションで指定した。schemaspy.propertiesにヒアドキュメントで書き出し読み込ませても良い。
    - java -jar schemaspy.jar -dp .
      -t pgsql -db ${POSTGRES_DB} -host ${POSTGRES_HOST} -port ${POSTGRES_PORT} -u ${POSTGRES_USER} -p ${POSTGRES_PASSWORD}
      -o docs/schemaspy
      -vizjs
      -rails
  artifacts:
    paths:
      - docs/schemaspy

pages:
  stage: build
  image: asciidoctor/docker-asciidoctor
  script:
    - asciidoctor -D public 'docs/**/*.adoc'
    - cp -r docs/schemaspy public/
  needs:
    - erd
  artifacts:
    paths:
      - public

docs/index.adoc

= Documents

* link:schemaspy/[ERD]

現物

こちらに

• GitLab CI/CD + Pages
• GitHub Actions + Pages

の例を置いてます。