Alto DBFlute

Alto DBFluteスタイル

DBFluteには、アプリの外側で開発の ベース を支える機能が多くあります。

これらは、アプリで DBFlute を使ってなくても、そもそも Java や C# でなくても、開発・運用途中からでも、RDBさえそこにあれば 利用できます。これら機能を総称して、Alto DBFlute と呼びます。

(★)マークが付いているものは、環境上の敷居が低く気軽に利用できるものです。

開発DBアプローチ (v.s. DB変更インパクト)

SchemaHTML
テーブル定義書を自動生成 ※DB変更しても、常に最新のドキュメントをディベロッパーに
HistoryHTML
DB変更履歴を自動生成 ※どんなDB変更が行われたか?の情報を確実にディベロッパーに
ReplaceSchema
DB環境構築を自動化 ※DB変更しても、迅速に最新のスキーマをディベロッパーに

本番DBアプローチ (v.s. 運用後のDB変更)

AlterCheck
本番DBへ流す alter 文の整合性をチェック ※前のDB + alter = 最新create
SchemaSyncCheck
本番DBや結合DBなどのスキーマ差分チェック ※単純に二つのDBの差を調べる

ハイレベルReplaceSchema

TakeFinally
ReplaceSchemaのテストデータの業務的整合性チェック
DateAdjustment
ReplaceSchemaの日付データを相対的に動かして登録
LoadDataReverse
画面登録したデータをReplaceSchemaのデータとしてダンプ

ハイレベルスキーマ差分

CraftDiff
ReplaceSchemaで登録したテストデータの業務的整合性チェック

ハイレベルというかすでにDBじゃない

PropertiesHTML
.properties ファイルの環境ごとにキーチェックや鳥瞰ドキュメント

導入の流れ

何をするにしても、DBFlute をセットアップするところからです。

そして、まずは気軽に利用できる SchemaHTML や HistoryHTML のドキュメント自動生成から始め、徐々に ReplaceSchema などの環境を整えていくと良いでしょう。

DBFluteのセットアップ
EMecha、もしくは、DBFlute Intro でダウンロードから設定など
まずは、ドキュメント生成
まずは、SchemaHTML (テーブル定義書) から作ってみる
ReplaceSchemaで自動化
とにかくDDLを用意して、ReplaceSchemaで環境構築の自動化

DBFluteのセットアップ

やり方は大きく二つ

セットアップには、大きく二つあります。

Eclipse使っていれば
EMecha(Eclipseプラグイン) からダウンロードとDB接続設定
Javaじゃないとかなら
DBFlute Intro を使ってGUIだけでセットアップから実行まで

Eclipse使っていれば

Eclipseを使っているような環境であれば、まずは EMecha をインストールしてください。 単なるセットアップだけでなく、設定ファイルのエディター機能もあり、入れるに越したことはありません。

そして、Package Explore (パッケージ・エクスプローラー) から、右クリックして New - Other... DBFlute Wizards - DBFlute New Client を選択して、画面からDB接続情報などの基本設定を入力し、ボタンでDBFluteをダウンロードして、最後に Finish します。

EMechaのインストール
プラグイン更新サイトからインストール
DBFluteクライアントの新規作成
右クリックでウィザード画面を起動してダウンロードと設定

すると、以下のようなディレクトリが作成されているはずです。

e.g. DBFluteクライアントとDBFluteモジュールの関係 {exampledb, 1.0.0} @Directory
eclipse-project
 |-dbflute_exampledb   // DBFluteクライアント
 |  |-dfprop           // 設定ファイル(DBFluteプロパティ)のディレクトリ
 |  |-log              // DBFlute自体のログファイルのディレクトリ
 |  |-output           // SchemaHTMLやHistoryHTMLなどの出力先ディレクトリ
 |  |-playsql          // ReplaceSchema用のディレクトリ(DDLやテストデータなど)
 |  |-schema           // DBFluteの内部データを保持するディレクトリ(基本触らない)
 |  |-xxx.bat(sh)      // あとはバッチやシェルスクリプトなどがいっぱい
 |-mydbflute
    |-dbflute-1.0.0    // DBFluteモジュール ※基本的に触らない

dbflute_xxx を DBFluteクライアント、mydbflute を DBFluteモジュール と呼びます。この後の説明でも "DBFluteクライアントの..." とあれば、dbflute_xxx ディレクトリ配下のことを示します。

ディレクトリが存在しないとか、なんだか失敗していそうであれば、二つのディレクトリを削除して、もう一度やり直してみてください。

Javaじゃないとかなら

Eclipseを使っていない環境であれば(そもそもJavaじゃないとか)、GUIだけでセットアップから実行までできる DBFlute Intro がお奨めです。 独立したページで紹介していますのでそちらをご覧ください。

これ以降このページでは、Eclipseで利用するケース で説明をします。

まずは、ドキュメント生成

SchemaHTMLがはじめの第一歩

まずは、SchemaHTML (テーブル定義書) から作ってみると良いでしょう。

テーブル定義書が別途あったとしても、物理的なDBからのリバースされたドキュメントということで価値がありますし、カラム名やプロパティ名をコピーするのにも便利です。 SchemaHTML を自動生成する手順の中で自然と HistoryHTML (DB変更履歴) も自動生成されていきます。

JDBC, Docタスクで自動生成

Windows環境なら、以下の手順で二つの "DBFluteタスク" を実行します。

バッチを二つ叩く
Windowsなら、Eclipseで ctrl + shift + R (リソースの検索) して、jdbc.bat, doc.bat を叩きます。
Mac (Linux含む) なら、コマンドライン (ターミナルなど) から jdbc.sh, doc.sh を実行します。
※コンソールに BUILD SUCCESSFUL と表示されていれば成功!
output/doc に出力される
DBFluteクライアント(dbflute_xxx)の output/doc ディレクトリ配下に出力されます。
SchemaHTMLなら schema-xxx.html, HistoryHTMLなら history-xxx.html です。HistoryHTMLは一番最初は生成されず、DBが変更した後の二回目以降の実行で自動生成されます。

DBコメントのススメ

SchemaHTMLでは、テーブルやカラムのコメント(いわゆるDBコメント)を抽出して表示します。 しっかりと業務的な補足が書いてあると、より充実したドキュメントとなります。 多くのERDツールでDBコメントを付与して生成することができますので、ぜひ積極的に利用しましょう。

また、DBコメントの中にテーブルやカラムの "別名" (和名、日本語名)を入れておくと良いでしょう。 そのとき、コロン区切りで登録しておくと良いです。(このような形式で出力できるERDツールもあります)

別名: 説明
e.g. 会員名称: 会員のフルネーム、姓と名が空白区切り

そして、DBFluteに対して、デリミタ(区切り文字)がコロンであること、そして、コロンが無かった場合にそれは別名なのか説明なのか? を教えてあげると、DBFluteが別名を認識して SchemaHTML 上で綺麗に表示します。

設定ファイルは、DBFluteクライアント(dbflute_xxx)の dfprop/documentDefinitionMap.dfprop です。EMechaが入っていれば、アイコンが "ヘ音記号" になっています。"#" (シャープ) はコメントマークです。コメントを外してプロパティを設定しましょう。

デリミタの設定
aliasDelimiterInDbComment に : を指定
デリミタなしの判定
デリミタなしのときは別名なら isDbCommentOnAliasBasis を true に
e.g. DBコメントのデリミタをコロンに、デリミタなければ別名で @documentDefinitionMap.dfprop
    ...

    # /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # o aliasDelimiterInDbComment (NotRequired - Default '')
    #  If the alias exists in its DB comment like as follows:
    #    member name : The name of member's full name
    #  you can use the alias in DBFlute world, java-doc, SchemaHTML...
    #  DB comment which does not have the delimiter is not treated
    #  as alias, treated as description (real comment).
    #  But you can change it by 'isDbCommentOnAliasBasis'.
    #
    ; aliasDelimiterInDbComment = :
    # - - - - - - - - - -/

    # /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # o isDbCommentOnAliasBasis (NotRequired - Default false)
    #  Is DB comment on alias basis?
    #  (Is DB comment alias name when it has no alias delimiter?)
    #  This property works with 'aliasDelimiterInDbComment'.
    #
    ; isDbCommentOnAliasBasis = true
    # - - - - - - - - - -/

    ...

その後のドキュメント運用

バージョン管理システムへコミット
自動生成されたら、ディベロッパー全員で共有するためにバージョン管理システム(GITやSVNなど)へコミットすると良いでしょう。 DBFluteクライアント (dbflute_xxx) と、DBFluteモジュール (mydbflute) ごと一緒にコミットしておきましょう。 (DBFluteクライアントの log ディレクトリのログファイルは ignore 設定にしておくと良いでしょう)
DBが変更されたらまた叩く
DB変更されたら、また同じようにJDBCタスク、Docタスクを叩くと SchemaHTML が更新(上書き)されます。そのときのDB変更の差分情報が、HistoryHTMLに追加されます。
SchemaHTMLをブックマーク
パッと開いてパッとスキーマ情報を見られるのが SchemaHTML の特徴です。 普段よく使っているブラウザのブックマーク(お気に入り)に登録して、すぐに開けるようにしましょう。 ディベロッパーにそのように横展開しましょう。
カラムの定義順やDBコメントの差分
これはオプションであり、デフォルトでは差分チェックされません。カラムの定義順の調整ができないDBMSもあるのと、DBコメントまで差分にすると差分ノイズになってしまう可能性があるためです。
差分チェック対象にしたい場合は、documentDefinitionMap.dfprop の isCheckColumnDefOrderDiff や isCheckDbCommentDiff を true に設定します。
ストアドプロシージャの差分
こちらもオプションであり、デフォルトでは差分チェックされません。プロシージャを利用するプロジェクトでは有用ですので、そのときは documentDefinitionMap.dfprop の isCheckProcedureDiff を true にすると良いでしょう。(行数、文字数、ハッシュ値で比較し、変更があったことだけを検知します)
マスタデータも差分履歴に
区分値や固定参照情報などのマスタデータ、VIEWのSQLの中身(select句の構造は既に差分チェックされますが、SQLの中身はデフォルトではチェックされない)、 DB権限やDBMSの設定など、とにかく SQL で抽出できるデータであれば、差分チェック対象にすることができます。
特に、区分値系のマスタデータの変更はディベロッパーにとってプログラミングする上での大事な情報です。CraftDiff を使って、差分チェック対象にしておくと良いでしょう。

ReplaceSchemaで自動化

様々な機能の土台となる

ReplaceSchemaは、単に開発DBの環境構築を自動化するだけでなく、テストデータの一元管理や整合性のチェック、運用後のDB変更で活躍するalter文のチェック (AlterCheck) の土台にもなります。

ちょっとだけ最初の構築は気を使いますが、一度作ってしまえばあとは横展開するだけです。

とにかく、DDLの準備

とにかく、DDLを準備しましょう。 ERDツールなどから create table 文が自動生成できると良いです。

そのDDLを、ReplaceSchemaのディレクトリである、DBFluteクライアント(dbflute_xxx)の playsql ディレクトリの replace-schema.sql に転記します。ERDツールから出力するときに直接上書きすると良いでしょう。

e.g. DBFluteクライアントとDBFluteモジュールの関係 {exampledb, 1.0.0} @Directory
eclipse-project
 |-dbflute_exampledb   // DBFluteクライアント
 |  |-...
 |  |-playsql
 |  |  |-replace-schema.sql    // ここにDDLを出力する
 |  |  |-take-finally.sql      // この時点ではまだ空っぽ、TakeFinallyで利用

もし、すでに同じ名前のスキーマ(データベース)がある場合、データもろとも消えちゃってもよろしいでしょうか? (もしくは、DB接続情報で設定されているスキーマとユーザーは作成されていますか?)

特に問題なければ、ctrl + shift + R (リソースの検索) で replace-schema.bat を叩いてください(Macならコマンドから)。すると、本当にOKかどうか? を聞かれますので、表示されているDB接続先情報などを確認してOKならば、"y" を押して Enter しましょう。最後に BUILD SUCCESSFUL が表示されていれば、DDLが正常に実行された証です。

新規でテストデータを作成

まだこの状態だとデータが空っぽですっからかんなので、アプリは動きません。 区分値や固定参照情報などのマスタデータは必要ですし、業務データのテストデータもある程度あったほうが良いでしょう。

ReplaceSchema の "データ登録(エクセル)" のページを参考に、テストデータをエクセルファイルで作成して、所定の位置に配置していってください。 そして、ReplaceSchema を実行すると、それらデータが登録されるようになります。

e.g. エクセルファイルの配置: 会員系テーブルのエクセルファイル @playsql
eclipse-project
 |-dbflute_exampledb   // DBFluteクライアント
 |  |-...
 |  |-playsql
 |  |  |-data          // ReplaceSchemaで登録するデータを配置するディレクトリ
 |  |  |  |-common     // 本番、結合、開発でも変わらないデータを配置するディレクトリ
 |  |  |  |  |-xls
 |  |  |  |     |-10-master.xls
 |  |  |  |-ut         // 開発で使うテストデータを配置するディレクトリ
 |  |  |  |  |-xls
 |  |  |  |     |-20-member.xls
 |  |  |  |     |-30-product.xls
 |  |  |-replace-schema.sql
 |  |  |-take-finally.sql
e.g. エクセルファイルの中身: 会員系テーブルのエクセルファイル @xls
|MEMBER_ID|MEMBER_NAME|BIRTHDATE |
|        1|Stojkovic  |1965/03/03|
|        2|Savicevic  |          |
|        3|...        |...       |
- - - - - - - - - - - - - - - - - -
MEMBER / MEMBER_LOGIN / MEMBER_SECURITY <-- Sheet

既存のテストデータを流用

既存のスキーマに残しておきたいテストデータがある場合は、そのテストデータを LoadDataReverse でエクセル抽出して、そのまま ReplaceSchema で登録するテストデータにしてしまいましょう。

documentDefinitionMap.dfprop の loadDataReverseMap のコメントを外し、isReplaceSchemaDirectUse を true にして、ctrl + shift + R (リソースの検索) で manage.bat を叩いて(もちろん、Macならコマンドぉー)、コンソールに表示される LoadDataReverse に該当する番号を入力して Enter しましょう。

e.g. LoadDataReverseで、レコード数を無制限でReplaceSchema直接利用 @documentDefinitionMap.dfprop
    ...

    # /- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    # o loadDataReverseMap: (NotRequired - Default map:{})
    #  You can set LoadDataReverse settings.
    #  This property is valid when the property 'recordLimit' is set.
    #  Elements of this map are as below:
    #   o recordLimit: The limit of records to output. Minus means no limit. (NotRequired - Default '')
    #   o isReplaceSchemaDirectUse: Does it output the data to playsql directly? (NotRequired - Default false)
    #   o isOverrideExistingDataFile: Does it output to existing files? (NotRequired - Default false)
    #   o isSynchronizeOriginDate: Does it synchronize origin date for date adjustment? (NotRequired - Default false)
    #
    ; loadDataReverseMap = map:{
        ; recordLimit = -1
        ; isReplaceSchemaDirectUse = true
        ; isOverrideExistingDataFile = false
        ; isSynchronizeOriginDate = false
    }
    # - - - - - - - - - -/

    ...

すると、DBFluteクライアントの playsql/data/ut/reversexls ディレクトリに配下に cyclic-data-[セクション番号]-xxx.xls という名前でデータがダンプされています。この状態で、ReplaceSchema を叩くと、それらエクセルデータも一緒に登録されます。(ただし、データの微調整が必要になる可能性もあり)

土台ができれば自然とハイレベルに

ひとまずの環境ができました。あとはバージョン管理システムにDBFluteまるごとコミットして、ディベロッパーに更新してもらって ReplaceSchema を叩いてもらえけば(スキーマとユーザーはあらかじめ作成してもらう必要あり)、開発用DBの環境構築がバッチ一発で完成します。 その後、DB変更が発生したら新DDLと修正テストデータをコミットして、また叩き直してもらえば良いのです。

また、スキーマとユーザーの作成も自動化することもできます。

ReplaceSchemaは、様々な機能を備えています。徹底したテストデータのマネジメント、本番DBと開発DBにズレを生じさせないための AlterCheck など、スムーズで快適なDB変更ライフを送るために、ちょっとずつでいいので現場にフィットするように環境構築していってみてください。

TakeFinally
ReplaceSchemaのテストデータの業務的整合性チェック
DateAdjustment
ReplaceSchemaの日付データを相対的に動かして登録
LoadDataReverse
画面登録したデータをReplaceSchemaのデータとしてダンプ
AlterCheck
本番DBへ流す alter 文の整合性をチェック ※前のDB + alter = 最新create
CraftDiff
ReplaceSchemaで登録したテストデータの業務的整合性チェック

単純に二つのスキーマを比べる

単純に二つのスキーマを比べて差分があるかどうかを調べたいのであれば、SchemaSyncCheck を使うと良いでしょう。 仕組みがシンプルなので、様々なシチュエーションで活用できるかと思います。

例えば、もろもろの事情により ReplaceSchema を導入できず AlterCheck が利用できない場合は、SchemaSyncCheck を使って開発DBや結合DB、本番DBなどの差分をチェックすると良いでしょう。

チュートリアルを参考に

DBFluteのもろもろの情報を得るために、チュートリアルのページが参考になります。

jfluteのコラムに注目

なぜ、アルトフルート?

アプリの外側、開発環境や運用の部分を ベースパート と捉えて、メロディーではなくベースを奏でるものとしてという感じですね。 まあ、DBFluteをメインで使うわけではないけれども、あると便利かなという...