AlterCheck を Intro で

• Introで!? の概要
  • 対応バージョン
  • そもそも AlterCheck とは？
  • そもそも DBFlute Intro とは？
  • Intro経由だと何が嬉しい？
• AlterCheckの画面はどこにある？
  • DBFlute Intro を起動
  • サイドメニューのAlterCheck
  • 操作の流れ、2つのステップ
• Step1. AlterCheckの下準備をする
  • Step1画面での操作
  • リリース前のAlterDDLを確認する
  • AlterCheckの準備をする
• Step2. AlterCheckを実行する
  • Step1画面での操作
  • AlterDDLを編集する
  • AlterCheckを実行する
  • AlterCheck失敗の理由を確認する
  • Step1画面に戻ったら...

Introで!? の概要

対応バージョン

DBFlute Intro-0.3.6 よりサポートされています。対応する DBFlute は、AlterCheckがリニューアルされたバージョン 1.2.1 以降でも、それよりも前のバージョンでも、どちらでも動作します。

そもそも AlterCheck とは？

DB変更を加えるときに、差分DDLが妥当かどうかをReplaceSchemaを利用して検証するDBFlute Engineの機能です。AlterCheckそのものの詳しい内容はこちらをお読みください。

そもそも DBFlute Intro とは？

DBFlute を GUI (webアプリ) で操作できるツールです。 DBFluteの物理的な構造をあまり知らなくても(覚えてなくても)、DBFluteタスクを実行したり、設定ファイルを修正したりすることができます。

Intro経由だと何が嬉しい？

AlterCheckの作業は、DBFlute規約であるディレクトリやファイルの物理構造を意識する必要があります。 毎日行うような作業でもないので、常にドキュメントを読みながらの不慣れな状態での作業となり、ケアレスミスも時に発生しするでしょう。

DBFlute Intro の画面を使えば、そういった物理構造をあまり意識する必要がありません。UIによるレールを敷いて、ケアレスミスが極力減るようにデザインされています。

AlterCheckの画面はどこにある？

DBFlute Intro を起動

manage.sh|bat の 88 (intro) を実行して、Introを起動しましょう。(常に最新版が起動します)

サイドメニューのAlterCheck

DB変更に対応するDBFluteクライアントを選び、サイドメニューにある、AlterCheckリンクからAlterCheck画面に移動することができます。

AlterCheck画面

操作の流れ、2つのステップ

そして、AlterCheckのステップを踏んでいきます。(大きく分けて2つのステップ)

• Step1. AlterCheckの下準備をする
• Step2. AlterCheckを実行する

Step1. AlterCheckの下準備をする

Step1画面での操作

この画面で行う操作は2つあります。

• リリース前のAlterDDLを確認する
• AlterCheckの準備をする

Step1画面

リリース前のAlterDDLを確認する

Step1の画面で表示されているのは、（他の人が作業した）未リリースでチェック済みのAlterDDLの一覧です。 ファイル名をクリックすることで、AlterDDLの中身を確認することができます。この時点で、自分の入れたいDB変更がすでに入っていないか（重複していないか）確認してください。

e.g. Step1画面でリリース前のAlterDDLの中身を確認する

GUIで操作する以上、あまり意識する必要はありませんが、表示しているAlterDDLの実態となるファイルは以下のディレクトリに配置されているものです。
unreleased-checked-alter 配下にあるファイルは、SQLファイルのみ表示しています。

e.g. AlterDDLの保存場所
dbflute_yourdb
 |-playsql
    |-migration // AlterCheck用のディレクトリのトップ
       |
       |-history // AlterCheckのSQLファイルの履歴ディレクトリ
          |-[日付]
          |  |
          |  |-[日時]
          |     | // 未リリースでチェック済みのAlterDDL @until DBFlute-1.2.0
          |     |-checked-alter...zip
          |
          | // 未リリースでチェック済みのAlterDDL @since DBFlute-1.2.1
          |-unreleased-checked-alter
             |-DONT_EDIT_HERE.dfmark
             |-for-previous-20120804-1746.dfmark
             |-READONLY_alter-schema.sql
             |-READONLY_alter-schema-[チケット番号].sql

AlterCheckの準備をする

新たにDB変更を加えAlterDDLを作成したい場合は、作成するAlterDDLのファイル名を入力して、Beginボタンを押してください。 リリース前のSQLを修正したい場合は、Fixボタンを押してください。 この操作を行うと、DBFluteクライアントプロジェクト内部でAlterCheckをする準備が整い、Step2に進みます。

Step1画面でAlterCheckの準備をする

AlterCheckの準備は、内部的にはDBFlute Engineのバージョンによって以下のことを行なっています。

@until DBFlute-1.2.0

AlterDDLを編集するディレクトリに、checked-alter...zip の中にあるCheck済みのAlterDDLを解凍して配置する。

@since DBFlute-1.2.1

AlterDDLを編集するディレクトリに、unreleased-checked-alterディレクトリの中にあるCheck済みのAlterDDLをコピーする。ただし、コピーするときに ファイル名からREADONLY_を削る。

準備後、DBFluteクライアントは以下のようになディレクトリ構造になっています。

e.g. AlterCheck準備後のディレクトリ構造
dbflute_maihamadb
 |-playsql
    |-data // ReplaceSchemaの登録データのディレクトリ
    |
    |-migration // AlterCheck用のディレクトリのトップ
       |
       |-alter  // AlterDDLを編集するディレクトリ (一時作業領域なのでgitignore推奨)
       |  |-alter-schema.sql
       |  |-alter-schema-[チケット番号].sql
       |
       |-history // AlterCheckのSQLファイルの履歴ディレクトリ
          |  |
          |  |-[日時]
          |     | // 未リリースでチェック済みのAlterDDL @until DBFlute-1.2.0
          |     |-checked-alter...zip
          |
          | // 未リリースでチェック済みのAlterDDL @since DBFlute-1.2.1
          |-unreleased-checked-alter
             |-DONT_EDIT_HERE.dfmark
             |-for-previous-20120804-1746.dfmark
             |-READONLY_alter-schema.sql
             |-READONLY_alter-schema-[チケット番号].sql

Step2. AlterCheckを実行する

Step1画面での操作

この画面で行う操作は3つあります。

• AlterDDLを編集する
• AlterCheckを実行する
• AlterCheck失敗の理由を確認する

Step2画面

AlterDDLを編集する

Step2画面では、編集中のAlterDDL一覧が表示されています。 (now prepared) と末尾に書かれているファイルが、Step1でファイル名を入力することで作成されたファイルです。
編集中のAlterDDLが格納されているディレクトリをみなさんのOSに搭載されているファイルエクスプローラで開くには、SQL Files Directory ボタンを押します。 ここから、任意のエディタを利用して、AlterDDLを編集してください。

Step2画面でAlterDDLを編集する（Macの例）

e.g. ボタンを押すと開くディレクトリの場所
dbflute_yourdb
 |-playsql
    |-migration // AlterCheck用のディレクトリのトップ
       |-alter // AlterDDLを書くディレクトリ (一時作業領域なのでgitignore推奨)
             |-alter-schema.sql
             |-alter-schema-[チケット番号].sql

AlterCheckを実行する

AlterDDLの編集が終わったら、Execute AlterCheck ボタンを押してください。 確認ダイアログが表示され、OKボタンを押すとAlterCheckを実行されます。 AlterCheckが正常に終わった場合に、Step1画面に自動的に戻ります。

Step2画面でAlterDDLを実行する（Macの例）

AlterCheck失敗の理由を確認する

AlterCheckに失敗した場合、失敗した理由を確認し、再度AlterDDLを修正しなければなりません。 修正の鍵となる2つの情報がStep2画面上から確認できます。これらの情報はAlterCheckが失敗したあとから確認できるようになります。

Check Result HTML

PreviousDDLにAlterDDLを流したあとに、NextDDLと差分があった場合にDBFlute Engineによって作成されるHTMLファイルです。 DDL間にどのような差分があったのかがわかるようなドキュメントになっています。 このHTMLファイルは、DDL間に差分があったという理由で以外でAlterCheckに失敗した場合は作成されません。

AlterCheckの最終実行ログ

Check Result HTMLだけでAlterCheckにしっぱした理由がわからない場合はこちらを確認してください。 AlterCheckが失敗した理由が詳細に記載されています。 「どのAlterDDLの実行に失敗したのたのか」や、「DB接続に失敗した」などのAlterCheck失敗に関する様々な原因を確認することができます。

AlterCheck失敗理由の確認

Step1画面に戻ったら...

晴れてAlterCheckがうまくいきました！！
またDB変更をする場合は、Step1画面から作業を繰り返してください。