decochのブログ

フリーランスのiOSエンジニア decoch のブログです

DBFlute Intro を使ってデータベースのドキュメント管理を楽にしよう

以前、開発人数の多いサービスで働いているメンバーから、「データベースにコメントは残したいんだけど、DB変更の手順が面倒だったり、レビューにはDBAの人が必要で気軽にできないんだよー」という悩みを耳にしました。
DBFlute Intro ではDB変更なしでドキュメントの更新、コメント追加が行える機能を開発しました。
今回はその手順をまとめました。

目次

  • そもそもSchemaHTML とは
  • ドキュメントの表示手順
  • ドキュメントの更新方法
  • チームでのドキュメントの共有方法
  • まとめ

そもそもSchemaHTML とは

DBFlute Intro では SchemaHTMLという、スキーマメタデータ(テーブル構成など)を人が見やすい形にまとめたドキュメントを閲覧することができます

f:id:decoch:20190803095140p:plain
schema html

詳しくはこちらをご覧ください dbflute.seasar.org

ドキュメントの表示手順

1.DBFlute Intro のダウンロード

Githubのリリースページ から最新の jar ファイルをダウンロードします

f:id:decoch:20190803103043p:plain
github release

2.ダウンロードした jar ファイルを「右クリック」をして「開く」を押すと数秒後にブラウザで自動的に立ち上がります。

f:id:decoch:20190803103129p:plain
download

3.立ち上がった画面にドキュメント生成したいDBの情報を入力します

f:id:decoch:20190803103351p:plain
dbflute intro welcome page

4.DBのセットアップが完了するとTOP画面遷移するので、生成したDB名をクリックします

f:id:decoch:20190803112158p:plain
client

すると以下画面が表示されるので、「Generate Documents」をクリックすると数秒後にドキュメントへのリンクが表示されます

f:id:decoch:20190803103501p:plain
dbflute intro document

f:id:decoch:20190803103701p:plain
クリック後

5.実際にドキュメントを開きます

f:id:decoch:20190803103759p:plain
schema document

ドキュメントの更新方法

SchemaHTMLの更新したいテーブルや、カラムのコメント部分をクリックします。(表の「Table Comment、Column Comment」)

ダイアログが立ち上がるのでコメントを変更して「OK」をクリックします

f:id:decoch:20190803110554p:plain
decomment

するとコメントが変更され、誰が書いたのか auther名が追加されます

変更前 f:id:decoch:20190803110945p:plain

変更後 f:id:decoch:20190803110948p:plain

またDB変更があったときには、「Generate Documents」をクリックすると作成したコメントを残したままDB変更をドキュメントに反映をすることができます

チームでのドキュメントの共有方法

jar ファイルをダウンロードしたディレクトリを見ると、いくつかディレクトリができています。 コメントはこのディレクトリでファイル管理されているので、これらまとめて開発チームの git レポジトリとして共有するとドキュメントの共有をすることができます。

※ 以下の様なディレクトリなら my-project を Git 管理する

f:id:decoch:20190803112645p:plain
finder

まとめ

  • DBコメントは管理したいが気軽に変更しづらい
  • DBFlute Intro では ドキュメントの自動生成とコメントの気軽な更新ができる
  • チーム内での共有は Git レポジトリを用意すれば簡単にできる