<?xml version="1.0" encoding="UTF-8"?>
<document>
	<properties>
		<title>S2JDBC-Gen - Migrate</title>
	</properties>
	<body>
		<section name="Migrate">
			<ul>
				<li>
					<p>
						<a href="#説明">説明</a>
						<ul>
							<li>
								<p>
									<a href="#概要">概要</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#処理の流れ">処理の流れ</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#バージョン番号">バージョン番号</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#ディレクトリとファイルの処理順序">ディレクトリとファイルの処理順序</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#任意のSQLの実行">任意のSQLの実行</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#マイグレーションを初めて実行する際の注意点">マイグレーションを初めて実行する際の注意点</a>
								</p>
							</li>
						</ul>
					</p>
				</li>
				<li>
					<p>
						<a href="#パラメータ">パラメータ</a>
						<ul>
							<li>
								<p>
									<a href="#トップレベルのパラメータ">トップレベルのパラメータ</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#ネストした要素として指定されるパラメータ">ネストした要素として指定されるパラメータ</a>
								</p>
							</li>
						</ul>
					</p>
				</li>
				<li>
					<p>
						<a href="#例">例</a>
						<ul>
							<li>
								<p>
									<a href="#マイグレーション先のバージョン番号を指定する">マイグレーション先のバージョン番号を指定する</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#トランザクション内でマイグレーションを実行する">トランザクション内でマイグレーションを実行する</a>
								</p>
							</li>
							<li>
								<p>
									<a href="#環境名つきバージョンディレクトリ以下のファイルを優先する">環境名つきバージョンディレクトリ以下のファイルを優先する</a>
								</p>
							</li>
						</ul>
					</p>
				</li>
			</ul>
		</section>
		<section name="説明">
			<subsection name="概要">
				<p>
					データベーススキーマに定義されたオブジェクトをdrop &amp; createし、データをロードすることでデータベーススキーマのマイグレーションを行います。
				</p>
				<p>
					このタスクを実行する前に、<a href="gen_ddl.html">Gen-Ddl</a>によってDDLファイルやダンプファイルが生成されていなければいけません。
				</p>
			</subsection>
			<subsection name="処理の流れ">
				<p>
					デフォルトの処理の流れを説明します。
				</p>
				<p>
					Migrateタスクは、まず、現在のデータベーススキーマのバージョン番号をschemaInfoFullTableName属性に指定したテーブルから取得します（テーブルが存在しない場合は0になります）。
					次に、移行先のバージョン番号をddlInfoFile属性に指定したテキストファイルから取得します（ファイルが存在しない場合は0になりますが、Gen-Ddlタスクを実行していれば存在するはずです）。
					それから、現在のスキーマのバージョン番号に対応するディレクトリを選択し、その直下のdropディレクトリ以下にあるDDLファイルを実行します。
					この処理により、古いオブジェクトが削除されます。
					その後、移行先のバージョン番号に対応するディレクトリを選択し、その直下のcreateディレクトリ以下にあるDDLファイルの実行とダンプファイルのロードを行います。
					この処理により、新しくオブジェクトが作成され、schemaInfoFullTableName属性に指定したテーブルに移行先のバージョン番号が格納されます。
					また、ダンプファイルが存在する場合はデータがテーブルにロードされます。
					以上で、マイグレーションが完了します。
				</p>
				<p>
					マイグレーション後にダンプファイルを修正してデータをロードしなおしたい場合は、再度Migrateタスクを実行してください。
					この場合、現在のスキーマのバージョン番号と移行先のバージョン番号が同じになりますが、実行される処理の流れはバージョン番号が異なる場合と同様です。
					つまり、現在のスキーマのバージョン番号と移行先のバージョン番号が同じであれば、同じバージョンディレクトリ以下のdropディレクトとcreateディレクトリが処理されます。
				</p>
			</subsection>
			<subsection name="バージョン番号">
				<p>
					データベーススキーマのバージョン番号は、schemaInfoFullTableName属性に指定したテーブルで管理されます。
					どのカラムにバージョン番号を格納するかについては、schemaInfoColumnName属性で指定できます。
					このバージョン番号は、データベーススキーマがどのDDLのバージョンを使用して作成されたかを示します。
				</p>
				<p>
					テーブルの作成やバージョン番号の更新は、Migrateタスクにより自動で行われます。
				</p>
			</subsection>
			<subsection name="ディレクトリとファイルの処理順序">
				<p>
					dropディレクトリとcreateディレクトリどちらを対象にするにせよ、同じ階層に存在するファイルやディレクトリは名前で昇順にソートされ処理されます。
					たとえば、dropディレクトリの直下に010-foreignkeyと030-uniquekeyの2つのディレクトリがある場合、010-foreignkey、030-uniquekeyの順番で処理されます。
					しかし、もし、それら2つに加え020-sequenceというディレクトリがあれば、順番は、010-foreignkey、020-sequence、030-uniquekeyとなります。
				</p>
				<p>	
					Migrateタスクは、ディレクトリについてはその階層を下へ辿ります。ファイルについては拡張子に従って処理します。
				</p>
				<ul>
					<li>
						<p>
							拡張子がsqlもしくはddlの場合、データはSQLとみされデータベースに対し発行されます。
						</p>
					</li>
					<li>
						<p>
							拡張子がcsvの場合、データはCSV形式のダンプファイルとみなされデータベースにロードされます。
						</p>
					</li>
					<li>
						<p>
							その他の拡張子を持つファイルについては、何の処理も行われません。
						</p>
					</li>
				</ul>
			</subsection>
			<subsection name="任意のSQLの実行">
				<p>
					SQLを記述したファイルをdropディレクトリやcreateディレクトリ以下に配置することで、任意のSQLを実行できます。
					ファイルの形式については<a href="../file_format.html#SQLファイル">SQLファイル</a>を参照してください。
				</p>
				<p>
					この機能を利用することで、<a href="gen_ddl.html">Gen-Ddl</a>タスクでは生成できないストアドプロシージャ/トリガー/ビューに関するDDLや、データの整合性を確認するためのSQLを実行できます。
				</p>
				<p>
					たとえば、ビューに関するDDLを実行する場合、ビューの作成と削除のためのDDLをemployeeView.sqlという2つのファイル
					に記述し、次のように配置できます。
				</p>
<source><![CDATA[db
└─migrate
    └─0002
        ├─create
        │  ├─...
        │  └─061-view
        │      └─employeeView.sql
        └─drop
           ├─001-view
           │  └─employeeView.sql
           └─...]]></source>
				<p>
					上記のように配置した場合、employeeView.sqlは<a href="ディレクトリとファイルの処理順序">ディレクトリとファイルの処理順序</a>
					で示した順序に従って自動で実行されます。
				</p>
				<p>
					dropディレクトリやcreateディレクトリ以下に追加したディレクトリやファイルは、<a href="gen_ddl.html#タスク実行時のファイルのコピー">Gen-Ddlタスクによる自動コピー</a>の対象になります。
				</p>
			</subsection>
			<subsection name="マイグレーションを初めて実行する際の注意点">
				<p>
					マイグレーションを初めて実行する際、つまり、バージョン番号0のディレクトリで管理されたDDLを実行する際ですが、
					S2JDBC-Genからは知りえない名前の制約（主キー、外部キー、一意キー等）がデータベーススキーマに存在すると、マイグレーションに失敗することがあります。
					これは、<a href="gen_entity.html">Gen-Entityタスク</a>を使って既存のデータベーススキーマからエンティティを生成するケースで起こりえます。
					Gen-Entityタスクでは、既存のデータベースで管理された制約の名前を取り込むことができないからです
				</p>
				<p>	
					マイグレーションを成功させるためには、既存データベースから不要なオブジェクトをあらかじめ削除しておくか、
					バージョン番号0のディレクトリで管理された削除用のDDLを修正して既存の制約名が削除されるように変更してください。
				</p>
				<p>
					既存のデータベーススキーマを使用せず、新規にS2JDBC-Genを使ってデータベーススキーマを定義していく場合には、問題ありません。
				</p>
			</subsection>
		</section>
		<section name="パラメータ">
			<p>
				Antタスクへのパラメータを以下に示します。
			</p>
			<subsection name="トップレベルのパラメータ">
				<table border="1" cellpadding="2" cellspacing="0">
					<tr><th>属性</th><th>説明</th><th>デフォルト値</th><th>必須</th></tr>
					<tr><td>classpathDir</td><td>エンティティクラスを含むクラスパスのディレクトリです。このディレクトリはタスクの実行時のクラスパスに含まれている必要があります。</td><td>-</td><td>YES</td></tr>
					<tr><td>rootPackageName</td><td>ルートパッケージ名です。</td><td>""</td><td>NO</td></tr>
					<tr><td>entityPackageName</td><td>エンティティクラスのパッケージ名です。エンティティクラスは、rootPackageNameとこの値をピリオドで連結したパッケージに配置されているとみなされます。</td><td>"entity"</td><td>NO</td></tr>
					<tr><td>entityClassNamePattern</td><td>このタスクで対象とするエンティティクラス名の正規表現です。</td><td>".*"</td><td>NO</td></tr>
					<tr><td>ignoreEntityClassNamePattern</td><td>このタスクで対象としないエンティティクラス名の正規表現です。</td><td>""</td><td>NO</td></tr>
					<tr><td>schemaInfoFullTableName</td><td>スキーマのバージョンを管理するテーブル名です。</td><td>"SCHEMA_INFO"</td><td>NO</td></tr>
					<tr><td>schemaInfoColumnName</td><td>スキーマのバージョンを管理するカラム名です。</td><td>"VERSION"</td><td>NO</td></tr>
					<tr><td>migrateDir</td><td>マイグレーション用のファイルを管理するディレクトリです。</td><td>"db/migrate"</td><td>NO</td></tr>
					<tr><td>ddlInfoFile</td><td>DDLのバージョン番号を管理するファイルです。</td><td>"db/ddl-info.txt"</td><td>NO</td></tr>
					<tr><td>versionNoPattern</td><td>バージョン番号のパターンです。バージョン番号に対応するディレクトリ名に使用されます。</td><td>"0000"</td><td>NO</td></tr>
					<tr><td>version</td><td>マイグレーション先のバージョンです。ここには、特定の文字列もしくはバージョン番号を表す数値を指定できます。文字列としては、最新のバージョン番号を表す"latest"、現在のデータベーススキーマの次のバージョンを表す"next"、現在のデータベーススキーマの1つ前のバージョンを表す"previous"の3つがサポートされています。数値としては、0以上2147483647以下の値でなければいけません。</td><td>"latest"</td><td>NO</td></tr>
					<tr><td>statementDelimiter</td><td>SQLステートメントの区切り文字です。</td><td>";"</td><td>NO</td></tr>
					<tr><td>blockDelimiter</td><td>SQLブロックの区切り文字です。指定しない場合は、データベースのデフォルトの区切り文字が使用されます。たとえば、SQL Serverでは"go"、Oralce Databaseでは"/"、MySQLでは"/"、DB2では"@"が使用されます。</td><td>-</td><td>NO</td></tr>
					<tr><td>ddlFileEncoding</td><td>DDLファイルのエンコーディングです。</td><td>"UTF-8"</td><td>NO</td></tr>
					<tr><td>dumpFileEncoding</td><td>ダンプファイルのエンコーディングです。</td><td>"UTF-8"</td><td>NO</td></tr>
					<tr><td>haltOnError</td><td>"true"の場合、スキーマを作成するSQLやデータのロードが失敗すると即座にエラーを返します。ただし、スキーマを削除する処理については、エラーが起きても処理を続行します。</td><td>"true"</td><td>NO</td></tr>
					<tr><td>loadBatchSize</td><td>ダンプファイルのデータをロードする際のバッチサイズです。</td><td>"10"</td><td>NO</td></tr>
					<tr><td>transactional</td><td>"true"の場合、単一のトランザクションとして実行します。</td><td>"false"</td><td>NO</td></tr>
					<tr><td>genDialectClassName</td><td>S2JDBC-Genのダイアレクトインタフェースの実装クラス名です。ここに指定するクラスはorg.seasar.extension.jdbc.gen.dialect.GenDialectインタフェースを実装している必要があります。指定しない場合は<a href="../s2jdbc_setup.html#ダイアレクト">S2JDBCのダイアレクト</a>に対応したデフォルトのクラスが使用されます。</td><td>-</td><td>NO</td></tr>
					<tr><td>configPath</td><td>JdbcManagerのコンポーネント定義を含む設定ファイルです。このタスクの実行に使用されます。</td><td>"s2jdbc.dicon"</td><td>NO</td></tr>
					<tr><td>env</td><td>環境名です。</td><td>"ut"</td><td>NO</td></tr>
					<tr><td>applyEnvToVersion</td><td>バージョンディレクトリに環境名を適用する場合"true"を指定します。trueを指定すると、通常のバージョンディレクトリよりも環境名つきバージョンディレクトリに存在するダンプファイルを優先してロードします。</td><td>"false"</td><td>NO</td></tr>
					<tr><td>jdbcManagerName</td><td>JdbcManagerのコンポーネント名です。接続先のデータベースはJdbcManagerのコンポーネント名によって決まります。</td><td>"jdbcManager"</td><td>NO</td></tr>
					<tr><td>factoryClassName</td><td>S2JDBC-Genの公開されたインタフェースの実装を作成するファクトリのクラス名です。S2JDBC-Genをカスタマイズする場合に独自のファクトリクラスを指定できます。ここに指定するクラスはorg.seasar.extension.jdbc.gen.internal.factory.Factoryインタフェースを実装している必要があります。</td><td>"org.seasar.extension.jdbc.gen<br />.internal.factory.FactoryImpl"</td><td>NO</td></tr>
					<tr><td>commandInvokerClassName</td><td>S2JDBC-Genのコマンドを呼び出すクラスの名前です。コマンドの呼び出し前後で任意の処理を実行したい場合に指定します。ここに指定するクラスはorg.seasar.extension.jdbc.gen.command.CommandInvokerインタフェースを実装している必要があります。</td><td>"org.seasar.extension.jdbc.gen<br />.internal.command.CommandInvokerImpl"</td><td>NO</td></tr>
					<tr><td>classpath</td><td>このタスクを実行する際のクラスパスです。</td><td>-</td><td>classpathrefが指定されていない場合YES</td></tr>
					<tr><td>classpathref</td><td>このタスクを実行する際のクラスパスの参照です。</td><td>-</td><td>classpathが指定されていない場合YES</td></tr>
				</table>
			</subsection>
			<subsection name="ネストした要素として指定されるパラメータ">
				<h4>
					jvmArg
				</h4>
				<p>
					このタスクの大部分の処理は別VMで行われます。VMに引数を渡す場合は&lt;jvmarg&gt;要素を使用します。
					これはAntのJavaタスクで使用できる&lt;jvmarg&gt;と同じです。
					使用可能な属性やネストした要素についてはAntのドキュメントを参照してください。
				</p>
			</subsection>
		</section>
		<section name="例">
			<subsection name="マイグレーション先のバージョン番号を指定する">
				<p>
					デフォルトでは、マイグレーション先のバージョン番号は最新の番号、つまりddlInfoFile属性に指定されたテキストファイルで管理する番号になります。
					最新のバージョン番号ではなく、任意のバージョン番号を指定するには、version属性を使用します。
					現在よりも古いバージョン番号を指定することも可能です。
				</p>
				<p>
					次の例では、マイグレーション先のバージョン番号に15を指定しています。
				</p>
<source><![CDATA[<migrate
    classpathDir="build/classes"
    rootPackageName="examples"
    version="15"
    classpathRef="classpath"
/>]]></source>
				<p>
					バージョン番号に対応するバージョンディレクトリはあらかじめ存在していなければいけません。
					version属性には、バージョンディレクトリ名ではなくバージョン番号を指定することに注意してください。
				</p>
			</subsection>
			<subsection name="トランザクション内でマイグレーションを実行する">
				<p>
					transactional属性に"true"を指定すると、マイグレーションの処理がトランザクション内で実行されます。
					マイグレーションに失敗した場合は、ロールバックにより変更が元に戻ります（ただし、RDBMSがトランザクション内でのDDL実行をサポートしていなければいけません）。
				</p>
<source><![CDATA[<migrate
    classpathDir="build/classes"
    rootPackageName="examples"
    transactional="true"
    classpathRef="classpath"
/>]]></source>
			</subsection>
			<subsection name="環境名つきバージョンディレクトリ以下のファイルを優先する">
				<p>
					applyEnvToVersion属性に"true"を指定すると、環境名つきバージョンディレクトリ以下に同名の相対パスで表されるファイルがあれば、そちらが優先されるようになります。
					設定例は次の通りです。
				</p>
<source><![CDATA[<migrate
    classpathDir="build/classes"
    rootPackageName="examples"
    applyEnvToVersion="true"
    env="ut"
    classpathRef="classpath"
/>]]></source>
				<p>
					環境名つきバージョンディレクトリとは、バージョン名と環境名を#で連結したディレクトリのことです。
					次の図で言えば、0001#utがバージョンディレクトリになります。
				</p>
<source><![CDATA[db
└─migrate
    ├─0001
    │  └─create
    │      ├─010-table
    │      │  ├─employee.sql
    │      │  └─address.sql
    │      │
    │      ├─040-dump
    │      │  ├─employee.csv
    │      │  └─address.csv
    │      │
    │      └─050-foreignkey
    │
    └─0001#ut
       └─create
           ├─010-table
           │  └─employee.sql
           │
           └─040-dump
              └─employee.csv]]></source>
				<p>
					この例では、employee.sqlやemployee.csvについては0001#utディレクトリ以下のものが使用され、
					0001ディレクトリ以下にあるemployee.sqlやemployee.csvは参照されません。
					address.sqlやaddress.csvについては通常のバージョンディレクトリ以下にあるものが使用されます。
				</p>
				<p>
					環境名つきバージョンディレクトリ以下のダンプデータは、<a href="dump_data.html">Dump-Dataタスク</a>により作成できます。
				</p>
			</subsection>
		</section>
	</body>
</document>
