データベースのテーブル定義書をhtml形式で自動生成する

データベースのテーブル定義書ってどうやって作っていますか？

1. 暖かみのある手作りのexcel
   そして実際のCREATE TABLE文を保存しているファイルとの乖離が忍び寄り...

2. ERWinやSI Object Browserのような商用製品を使う
   そこそこお金かかる & GUI前提なのでは? & あとそれgitとかでバージョン管理できんの?

3. CSE, pgAdmin, A5:SQL Mk-2 のような新旧さまざまなフリーソフトを使う
   UNIX系OSで実行できて、かつ、GUIじゃなくCLIでないと、Jenkins等のCIサーバ上での自動実行が難しいですよね

4. 軟弱者め。CREATE文やALTER文のSQLさえ死守しておけば、あとは例えばmysqlの show tables, show create table foobar みたいなコマンドをその都度たたけば済む話だろ。

そもそもテーブル定義書が先か、ER図が先か、CREATE TABLE文が先か、JavaのJPAにそったアノテーションつきのエンティティクラスが先か、といったところから考え始めると、その流派や方法論は実に様々です。

なんであれ、人間が読むためのテーブル定義書がまったく無いよりは有る方がよいでしょう。もちろん実際のDBに作成されているテーブルやカラムと乖離しているようでは無意味です。確実で手っ取り早くてどこででもたいてい使える方法の一つが、実際に稼働しているDBサーバのメタ情報にアクセスして全自動でテーブル定義を逆起こしする手法です。

DBFluteというJavaのO/Rマッパには、そんな機能が付属しています。たとえO/RマッパにDBFluteを使ってなくとも、というかそもそもJavaじゃなくてC#やRubyなんですけど、みたいなプロジェクトであっても、正しいテーブルが作られているテスト用（本番でもいいけど）のDBサーバのメタ情報をもとにテーブル定義書を作るという目的に限定すれば、これから説明する手法はどこででも使えるでしょう。DBFluteとmavenというツールの都合上JDKが必要ですが、どうせJenkinsでやるのですから、最低限、JenkinsマシンにだけJDKが入っていればそれでいいのです。

あらかじめ必要なもの

• JDK8以上. ただしDBFluteのバージョンを少し古くすればJava6でもOK
• JAVA_HOME環境変数をセットしておく
• あらかじめ目的のテーブル、インデックス、制約などが全て作成済みの、N/Wアクセス可能な状態のDBサーバ

これだけです。Mavenすら要りません。サンプルではmaven-wrapperを使っているので、mavenが無ければ自動ダウンロードされます。

サンプルプロジェクト

https://github.com/nabedge/dbflute-doc-sample がサンプルです。READMEに書いてあるとおりに作業すると、target/dbflute_dfclient/output/doc/schema-dfclient.html というファイルにテーブル定義書ができあがります。このサンプルではh2databaseをその都度作成してCREATE TABLEするところまでをmavenのcompileフェーズに含めることで、DBサーバがわりにしています。

READMEの手順をそのままJenkinsジョブ化するとこんな感じになるはずです

このジョブを自動実行させて、ジョブのurlの"lastSuccessfullBuild"の配下を見れば、常に最新のテーブル定義が見れるという寸法。 テーブル定義だけでなく、インデックスの情報、外部キーの状況なども見れるのが嬉しいですね。

参考

• Alto DBFlute | DBFlute