Posted inDatabase

SchemaSpyで手作業から解放：ERD図とデータベースドキュメントの自動化

Database tutorial - IT technology blog
Database tutorial - IT technology blog

背景：なぜデータベースドキュメントを手書きすべきではないのか？

100以上のテーブルがある「レガシー」なプロジェクトに、ドキュメントが1ページもない状態で放り込まれるのは、まさに悪夢です。MySQL Workbenchで各テーブルを一つずつ確認し、外部キーのリレーションを推測する作業には、多くのエンジニアが馴染みがあるでしょう。この方法は非常に時間がかかり、システムが肥大化するにつれてミスも発生しやすくなります。

Draw.ioやLucidchartを使ってERD図（Entity Relationship Diagram）を手書きするのも一つの解決策ですが、データベースはコードの変更に伴って常に変化します。インデックスのカラム追加やデータ型の変更を更新し忘れるだけで、そのドキュメントは瞬時に時代遅れの「ゴミ」と化してしまいます。これが、筆者がプロセス全体の自動化にSchemaSpyを愛用している理由です。

本質的に、SchemaSpyはデータベースをスキャンして詳細なHTMLダッシュボードを出力する Javaツールです。テーブルをリストアップするだけでなく、リレーション図を自動描画し、「孤立したテーブル」（どこにもリンクされていないテーブル）の特定や、インデックスが不足しているカラムの統計表示も行います。構造を理解するのに2日かかっていた作業が、今ではWebサイトを5分眺めるだけでシステム全体を把握できるようになります。

データエンジニア向けのちょっとしたヒント：スキーマのテストなどでCSVをJSONに素早く変換したい場合は、toolcraft.app/ja/tools/data/csv-to-jsonにあるツールが便利です。クライアントサイドで動作するため、プロジェクトのデータがサーバーに漏れる心配がなく、セキュリティ面でも非常に安全です。

インストール環境の準備

SchemaSpyをスムーズに動作させるには、Java Runtime (JRE)、JDBCドライバ、そして図を描画するためのGraphvizが必要です。

1. JavaとGraphvizのインストール

SchemaSpyはJava 8以降を必要とします。UbuntuやDebianの場合は、次の1行のコマンドでインストールできます。

sudo apt update && sudo apt install openjdk-11-jre graphviz -y

Graphvizを忘れないでください！これがないと、出力されるレポートは文字ばかりになり、このツールの視覚的な強みの80%が失われてしまいます。

2. Tải SchemaSpy và JDBC Driver

公式のGitHubから最新のschemaspy.jarを入手してください。次に、使用しているDBの種類（MySQL、PostgreSQL、SQL Serverなど）に対応するJDBCドライバをダウンロードします。

  • PostgreSQL: 公式サイトからpostgresql-x.x.x.jarファイルを使用します。
  • MySQL: mysql-connector-java-x.x.x.jarを使用します。

管理しやすいように、すべて一つのディレクトリにまとめるのがおすすめです。

mkdir ~/schemaspy-tool && cd ~/schemaspy-tool
wget https://github.com/schemaspy/schemaspy/releases/download/v6.1.0/schemaspy-6.1.0.jar -O schemaspy.jar
# Postgres 42.5.0 用のドライバをダウンロードする例
wget https://jdbc.postgresql.org/download/postgresql-42.5.0.jar

設定ファイルによるSchemaSpyの実行

長くて間違いやすいコマンドを毎回入力する代わりに、schemaspy.propertiesファイルを使用することをお勧めします。この方法なら、Gitを通じてチームメンバーと設定を簡単に共有できます。

schemaspy.properties ファイルのサンプル内容

schemaspy.t=pgsql
schemaspy.dp=./postgresql-42.5.0.jar
schemaspy.host=127.0.0.1
schemaspy.port=5432
schemaspy.db=my_project_db
schemaspy.u=db_user
schemaspy.p=secret_password
schemaspy.s=public
schemaspy.o=./output
schemaspy.vizjs=true

準備ができたら、次の「魔法のコマンド」を実行します：

java -jar schemaspy.jar -configFile schemaspy.properties

SchemaSpyがすべてのメタデータをスキャンします。完了したら、output/index.htmlを開いて視覚的な成果を楽しみましょう。

Dockerによるクイックデプロイ

マシンにJavaをインストールするのが面倒な場合は、Dockerが救世主となります。この方法は、特にCI/CDサーバーで実行する場合に非常にスマートです：

docker run --v $(pwd):/output --net=host schemaspy/schemaspy:6.1.0 \
-t pgsql -host localhost:5432 -db my_db -u user -p pass -o /output -dp /drivers/postgresql.jar

レポートからの情報活用

SchemaSpyのインターフェースには、システム最適化のために私が常に詳しくチェックしている3つのタブがあります：

  • Relationships: ドキュメントの魂です。ERD図はズームイン・アウトが可能で、各テーブルをクリックして親子関係を非常に素早く確認できます。
  • Anomalies: データベースの「診断」タブです。主キー（Primary Key）が不足しているテーブル、名前は同じでもデータ型が異なるカラム、孤立したテーブルなどがリストアップされます。技術的負債（technical debt）を解消するのに最適な場所です。
  • Columns: データベースの検索エンジンです。カラム名を入力するだけで、そのカラムが含まれているテーブルを特定できます。

ドキュメントを常に最新に保つためのCI/CD統合

長期間更新されていないドキュメントは、捨てるのと変わりません。GitLab CIやGitHub Actionsのワークフローに組み込むのが最善です。新しいマイグレーションがマージされるたびに、システムが自動的にSchemaSpyを実行し、ファイルをGitHub Pagesなどにプッシュするようにします。

これにより、フロントエンドエンジニアからBA（ビジネスアナリスト）まで、全員が共通のURLを通じて最新のスキーマを確認できるようになります。DBAも、データベースに小さな変更があるたびに呼び出される手間が省けます。

セキュリティに関する注意：本番環境で実行する場合は、information_schemaに対してSELECT権限のみを持つ専用ユーザーを作成してください。機密データを守るため、決してrootユーザーは使用しないでください。

データベースのドキュメント作成は退屈な作業になりがちですが、SchemaSpyはそれをプロフェッショナルな自動化体験に変えてくれます。このツールが、皆さんのプロジェクトをよりクリアでメンテナンスしやすいものにする助けになれば幸いです！

Share:
Tags: