はじめに
チーム開発において、データベースのドキュメント（テーブル一覧、テーブル詳細、E-R図など）は、多くのプロジェクトで欠かせないものだと思います。
しかし、正直なところ、これらのドキュメントを手作業で作成・更新するのは面倒で、つらいと感じることもあるのではないでしょうか。
私自身も過去に、ExcelやConfluenceでDBドキュメントを管理していた経験がありますが、以下のような課題を感じていました。
- ドキュメント作成・更新に時間がかかる
- レビュー工程があっても更新ミスや漏れが発生してしまう
- 実際のDBとドキュメントが乖離し、やがて参照されなくなってしまう
そこで今回は、これらの課題を解決するために「接続しているDBのスキーマを解析し、DBドキュメントを自動生成する」リバースエンジニアリングツールを2つ紹介します。
これらのツールを活用することで、上記の課題を解消し、より効率的にドキュメントを管理できます。
ツール紹介
Schemaspy
SchemaSpyはJava製のツールで、JDBCを使用してデータベースに接続し、スキーマ情報を解析してHTML形式のDBドキュメントを生成します。
主な特徴
- テーブル一覧、テーブル詳細情報（カラム、インデックス）、E-R図などをHTML形式で視覚的に表示
- MySQL、MariaDB、Oracle、PostgreSQL、SQL Server などの多くのDBMSをサポート
- Dockerイメージが提供されており、気軽に試せる
公式サイトのサンプルでは、SchemaSpyによって自動生成されるDBドキュメントの例を見ることができます。以下に一部を掲載します。
テーブル一覧
テーブル詳細
E-R図
tbls
tblsはGo製の軽量ツールで、SchemaSpyと同様に接続先のDBスキーマ情報を解析して、ドキュメントを生成します。
主な特徴
-
DBドキュメントの出力形式が豊富
- GMF形式をはじめ、DOT、PlantUML、Mermaid、Image(svg, png, jpg)、JSON、YAML、Excelなどといった様々な形式で出力が可能
-
シングルバイナリ形式で提供されるため導入が簡単で、CIに組み込みやすい
- GitHubリポジトリからバイナリをダウンロードするだけで利用可能
-
データベースのリント機能も提供
- カラムコメントやテーブルコメントの必須化など実現できる
- SchemaSpyと同様、幅広いDBMSに対応
- Dockerイメージも提供
こちらについても、実際にどのような出力がされるのか公式サンプル出力を確認してみましょう。
テーブル一覧
テーブル詳細
E-R図
ツール比較
Schemaspyとtblsの主な特徴を簡単に比較すると以下の通りだと思います。
| 特徴 | SchemaSpy | tbls |
|---|---|---|
| 言語 | Java | Go |
| 出力形式 | HTML形式 | 多様（Markdown、SVG、JSONなど） |
| 導入方法 | Dockerイメージ、JAR | シングルバイナリ、Dockerイメージ |
| リント機能 | ✗ | ◯（コメント必須化など） |
| CIへの組み込み | ◯ | ◎ |
GitHubリポジトリからバイナリをダウンロードするだけで利用できるので、tblsの方が導入は簡単かと思います。CIに組み込む際も、k1low/setup-tbls を利用すれば簡単にセットアップできます。
一方、SchemaSpyは視覚的なデザインが優れており、特にE-R図が見やすいという特徴があります。
CIに組み込んで使うとより便利
前述のツールはどちらもローカルで手動実行するだけでも便利ですが、CI（継続的インテグレーション）に組み込むことで、さらに効果を発揮します。
具体的には、次のような手順をイメージしています。
1. 特定のブランチへのコミットをトリガーに処理開始
2. DDL/DMLの変更差分を確認。差分がなければ処理を終了
3. DBマイグレーションを実行
4. SchemaSpy または tbls を利用してDBドキュメントを生成
5. 生成したDBドキュメントをS3などの静的ホスティング環境にアップロード
この流れを実現することで、DBドキュメントの最新状態をチーム全体で簡単に共有できます。手作業でドキュメント作成を行う際に発生していた更新ミスや漏れもなくなり、信頼できるドキュメントを自動的に生成できます。
具体的な実装例については、以下の記事が参考になります。