説明
概要
エンティティクラスのメタデータを読み取りDDLを生成します。 このタスクでは、次のオブジェクトのcreate文とdrop文を生成します。
- テーブル
- シーケンス
- 一意キー
- 外部キー
また、dump属性が"true"の場合、DDLファイルの生成と同時にデータベースのデータをCSV形式でダンプ出力します。 DDLファイルとダンプファイルは、migrateDir属性に指定されたディレクトリ以下に出力されます。
このタスクは、DDLを生成しますが、生成したDDLをデータベースへ適用させるわけではありません。 DDLのデータベースへの適用はMigrateタスクが担います。
ディレクトリ構成
デフォルトの属性値を利用する場合、Gen-Ddlタスクにより作成されるディレクトリの構成は次のようになります。
db └─migrate ├─0000 │ ├─create │ └─drop │ ├─010-foreignkey │ ├─020-sequence │ ├─030-uniquekey │ └─040-table ├─0001 │ ├─create │ │ ├─010-table │ │ ├─020-uniquekey │ │ ├─030-sequence │ │ ├─040-dump │ │ └─050-foreignkey │ └─drop │ ├─010-foreignkey │ ├─020-sequence │ ├─030-uniquekey │ └─040-table └─0002 ├─create │ ├─010-table │ ├─020-uniquekey │ ├─030-sequence │ ├─040-dump │ └─050-foreignkey └─drop ├─010-foreignkey ├─020-sequence ├─030-uniquekey └─040-table
db/migrateディレクトリ以下の、0000、0001、0002はDDLのバージョンを表すディレクトリです。 バージョンを表すディレクトリは、Gen-Ddlタスクを実行するごとに新しく作成されます。
バージョンを表すディレクトリの下にはcreateディレクトリとdropディレクトリがあります。 createディレクトリでは、データベースオブジェクトの作成用DDLとダンプデータを管理し、 dropディレクトリでは、データベースオブジェクトの削除用DDLを管理します。
createディレクトリとdropディレクトリの下には、各オブジェクト専用のDDLもしくはダンプデータを管理するためのディレクトリがあります。
バージョン番号
バージョン番号は、ddlInfoFile属性に指定したテキストファイルで管理されます。 バージョン番号は0から始まり、上限の2147483647まで1ずつ増分します。 バージョン番号を管理するテキストファイルは、番号を振り直すなどの特別な理由がない限り編集しないでください。
DDLファイル
テーブル
Gen-Ddlタスクでは次の3種類のテーブルに対してDDLを生成します。
- エンティティに対応するテーブル
- エンティティの識別子生成用テーブル
- スキーマのバージョンを管理するテーブル
エンティティの識別子生成用テーブルのDDLは、エンティティの識別子に@TableGeneratorを指定した場合に生成されます。
スキーマのバージョンを管理するテーブルのDDLは、Gen-Ddlタスクを実行すると必ず生成されます。 これは、データベーススキーマのバージョンを管理するテーブルです。 テーブル名やカラム名はschemaInfoFullTableName属性とschemaInfoColumnName属性で決まります。
シーケンス
シーケンスのDDLは、エンティティの識別子に@SequenceGeneratorを指定した場合に生成されます。
一意キー
一意キーのDDLを生成する方法は3つあります。
- @Columnのunique属性にtrueを指定する
- @TableのuniqueConstraints属性に値を指定する
- @TableGeneratorのuniqueConstraints属性に値を指定する
外部キー
外部キーのDDLは、エンティティクラスで関連プロパティを定義した場合に生成されます。
ダンプファイル
CSVの出力
ダンプファイルはCSV形式で出力されます。 CSVは次の規則を持ちます。
- ファイル名は、ロード時にテーブル名として利用されます(カタログ名やスキーマ名を含むこともあります)。したがって、修正しないでください。
- 最初の一行目はテーブルのカラムを表すヘッダー行になります。ヘッダー行は必須です。
- ヘッダー行とデータ行の列数は同じでなければいけません。
- null以外のすべてのデータはダブルクォテーションで囲むことができます(Gen-Ddlは必ずダブルクォテーションで囲んで出力します)。
- nullは長さ0のデータで表されます。ダブルクォテーションで囲んではいけません。ダブルクォテーションで囲まれた長さ0のデータは空文字列とみなされます。
CSV上のデータの形式は、エンティティのプロパティの型により決まります。
プロパティの型 | データの形式 |
---|---|
String、char/Character | 文字列表現です。ただし、ダブルクォテーション、カンマ、改行コードのいずれかを含む場合は、文字列全体がダブルクォテーションで囲まれる必要があります。そのとき、データとしてのダブルクォテーションはダブルクォテーションを2重にすることでエスケープされなければいけません。空文字は、ダブルクォテーションで囲まれる必要があります。 |
@Temporal(TemporalType.DATE)が指定されたjava.util.Date、@Temporal(TemporalType.DATE)が指定されたjava.util.Calendar、java.sql.Date | yyyy/MM/ddの形式でなければいけません。 |
@Temporal(TemporalType.TIME)が指定されたjava.util.Date、@Temporal(TemporalType.TIME)が指定されたjava.util.Calendar、java.sql.Time | hh:mm:ssの形式でなければいけません。 |
@Temporal(TemporalType.TIMESTAMP)が指定されたjava.util.Date、@Temporal(TemporalType.TIMESTAMP)が指定されたjava.util.Calendar、java.sql.Timestamp | yyyy/MM/dd hh:mm:ss.fffffffffの形式でなければいけません。ただし、.fffffffffについてはなくてもかまいません。 |
byte[]、Serializable | Base64でエンコードされた形式で表現されます。 |
Enumのサブクラス | S2JDBCで永続化される際に使用される値の文字列表現です。 |
その他の型 | 文字列表現です。 |
CSVの編集
CSV形式のデータを修正するには、Cassava Editor が便利です。 以下に、Cassava Editorのお奨めの設定方法を示します。
- メニューから「表示」-「一行目を固定」を選びます。これによりヘッダー行が固定されます。
- メニューから「オプション」-「オプション」を選びます。ダイアログが表示されたら「データ形式」を選択し、「必要なセルのみ""で囲む」にチェックします。これにより、nullのデータをnullのデータとして維持できます。
- メニューから「オプション」-「セーブ時文字コード」でdumpFileEncoding属性と同じエンコーディングを指定します。これにより、エンコーディングの誤変換を防ぎます。
データを修正する際は、上述の規則にしたがってください。
タスク実行時のファイルのコピー
Gen-Ddlタスクは、DDLやダンプデータを生成後、生成対象外かつ前バージョンのディレクトリに含まれるファイルを新しいバージョンのディレクトリにコピーします。 この仕組みにより、Gen-Ddlで生成される以外のファイルをGen-Ddlで生成されるファイルと同様の方法で管理できます。 たとえば、バージョン0002のcreateディレクトリの下に061-procedureや062-view、dropディレクトリの下に001-viewや002-procedureといったディレクトリを作成し、そこにストアドプロシージャーやビューの作成用DDLと削除用DDLファイルを置くとします。 Gen-Ddlタスクを実行すると、これらはバージョン0003のcreateディレクトリやdropディレクトリ以下にそのままコピーされます。
db └─migrate └─0002 ├─create │ ├─010-table │ ├─020-uniquekey │ ├─030-sequence │ ├─040-dump │ ├─050-foreignkey │ ├─061-procedure │ └─062-view └─drop ├─001-view ├─002-procedure ├─010-foreignkey ├─020-sequence ├─030-uniquekey └─040-table
パラメータ
トップレベルのパラメータ
属性 | 説明 | デフォルト値 | 必須 |
---|---|---|---|
classpathDir | エンティティクラスを含むクラスパスのディレクトリです。このディレクトリはタスクの実行時のクラスパスに含まれている必要があります。 | - | YES |
rootPackageName | ルートパッケージ名です。 | "" | NO |
entityPackageName | エンティティクラスのパッケージ名です。エンティティクラスは、rootPackageNameとこの値をピリオドで連結したパッケージに配置されているとみなされます。 | "entity" | NO |
entityClassNamePattern | このタスクで対象とするエンティティクラス名の正規表現です。 | ".*" | NO |
ignoreEntityClassNamePattern | このタスクで対象としないエンティティクラス名の正規表現です。 | "" | NO |
createTableDirName | テーブルを作成するDDLを格納するディレクトリ名です。 | "010-table" | NO |
createUniqueKeyDirName | 一意キーを作成するDDLを格納するディレクトリ名です。 | "020-uniquekey" | NO |
createSequenceDirName | シーケンスを作成するDDLを格納するディレクトリ名です。 | "030-sequence" | NO |
createForeignKeyDirName | 外部キーを作成するDDLを格納するディレクトリ名です。 | "050-foreignkey" | NO |
dropTableDirName | テーブルを削除するDDLファイル名です。 | "040-table" | NO |
dropUniqueKeyDirName | 一意キーを削除するDDLファイル名です。 | "030-uniquekey" | NO |
dropSequenceDirName | シーケンスを削除するDDLファイル名です。 | "020-sequence" | NO |
dropForeignKeyDirName | 外部キーを削除するDDLファイル名です。 | "010-foreignkey" | NO |
ddlFileEncoding | DDLファイルのエンコーディングです。 | "UTF-8" | NO |
sqlKeywordCase | SQLのキーワードを大文字にするか小文字にするかを指定する列挙型の値です。大文字にするには"uppercase"、小文字にするには"lowercase"を指定します。テンプレートに記述された文字をそのまま使用する場合は"originalcase"を指定します。 | "originalcase" | NO |
sqlIdentifierCase | SQLの識別子を大文字にするか小文字にするかを指定する列挙型の値です。大文字にするには"uppercase"、小文字にするには"lowercase"を指定します。エンティティに記述した文字をそのまま使用する場合は"originalcase"を指定します。 | "originalcase" | NO |
dump | "true"の場合、データベースのデータのダンプ出力を行います。 | "true" | NO |
dumpDirName | ダンプファイルの出力先のディレクトリです。 | "040-dump" | NO |
dumpFileEncoding | ダンプファイルのエンコーディングです。 | "UTF-8" | NO |
createTableTemplateFileName | テーブルを作成するDDLのテンプレートファイル名です。 | "sql/create-table.ftl" | NO |
createSchemaInfoTableTemplateFileName | スキーマ情報テーブルを作成するDDLのテンプレートファイル名です。 | "sql/create-schemainfo-table.ftl" | NO |
createUniqueKeyTemplateFileName | 一意キーを作成するDDLのテンプレートファイル名です。 | "sql/create-uniquekey.ftl" | NO |
createSequenceTemplateFileName | シーケンスを作成するDDLのテンプレートファイル名です。 | "sql/create-sequence.ftl" | NO |
createForeignKeyTemplateFileName | 外部キーを作成するDDLのテンプレートファイル名です。 | "sql/create-foreignkey.ftl" | NO |
dropTableTemplateFileName | テーブルを削除するDDLのテンプレートファイル名です。 | "sql/drop-table.ftl" | NO |
dropSchemaInfoTableTemplateFileName | スキーマ情報テーブルを削除するDDLのテンプレートファイル名です。 | "sql/drop-schemainfo-table.ftl" | NO |
dropUniqueKeyTemplateFileName | 一意キーを削除するDDLのテンプレートファイル名です。 | "sql/drop-uniquekey.ftl" | NO |
dropSequenceTemplateFileName | シーケンスを削除するDDLのテンプレートファイル名です。 | "sql/drop-sequence.ftl" | NO |
dropForeignKeyTemplateFileName | 外部キーを削除するDDLのテンプレートファイル名です。 | "sql/drop-foreignkey.ftl" | NO |
templateFileEncoding | テンプレートファイルのエンコーディングです。 | "UTF-8" | NO |
templateFilePrimaryDir | テンプレートファイルを検索する際の優先ディレクトリです。 | - | NO |
migrateDir | マイグレーション用のファイルを管理するディレクトリです。 | "db/migrate" | NO |
ddlInfoFile | DDLのバージョン番号を管理するファイルです。 | "db/ddl-info.txt" | NO |
versionNoPattern | バージョン番号のパターンです。バージョン番号に対応するディレクトリ名に使用されます。java.text.DecimalFormatで使用可能なパターンを指定できます。 | "0000" | NO |
statementDelimiter | SQLステートメントの区切り文字です。 | ";" | NO |
schemaInfoFullTableName | スキーマのバージョンを管理するテーブル名です。 | "SCHEMA_INFO" | NO |
schemaInfoColumnName | スキーマのバージョンを管理するカラム名です。 | "VERSION" | NO |
tableOption | CREATE TABLE文の最後に付与されるオプションです。MySQLで、データベースのエンジンを指定する場合、たとえば、"ENGINE = INNODB"というように指定できます。 | - | NO |
genDialectClassName | S2JDBC-Genのダイアレクトインタフェースの実装クラス名です。ここに指定するクラスはorg.seasar.extension.jdbc.gen.dialect.GenDialectインタフェースを実装している必要があります。指定しない場合はS2JDBCのダイアレクト に対応したデフォルトのクラスが使用されます。 | - | NO |
configPath | JdbcManagerのコンポーネント定義を含む設定ファイルです。 | "s2jdbc.dicon" | NO |
env | 環境名です。 | "ut" | NO |
jdbcManagerName | JdbcManagerのコンポーネント名です。 | "jdbcManager" | NO |
factoryClassName | S2JDBC-Genの公開されたインタフェースの実装を作成するファクトリのクラス名です。S2JDBC-Genをカスタマイズする場合に独自のファクトリクラスを指定できます。ここに指定するクラスはorg.seasar.extension.jdbc.gen.internal.factory.Factoryインタフェースを実装している必要があります。 | "org.seasar.extension.jdbc.gen .internal.factory.FactoryImpl" |
NO |
commandInvokerClassName | S2JDBC-Genのコマンドを呼び出すクラスの名前です。コマンドの呼び出し前後で任意の処理を実行したい場合に指定します。ここに指定するクラスはorg.seasar.extension.jdbc.gen.command.CommandInvokerインタフェースを実装している必要があります。 | "org.seasar.extension.jdbc.gen .internal.command.CommandInvokerImpl" |
NO |
classpath | このタスクを実行する際のクラスパスです。 | - | classpathrefが指定されていない場合YES |
classpathref | このタスクを実行する際のクラスパスの参照です。 | - | classpathが指定されていない場合YES |
例
SQLのキーワードと識別子の大文字小文字を指定する
sqlKeywordCaseType属性とsqlIdentifierCaseType属性に"uppercase"や"lowercase"といった値を指定することで、SQLのキーワード(CREATEやALTERなど)やSQLの識別子(テーブル名やカラム名)の大文字小文字を指定できます。 たとえば、次のように指定できます。
<gen-ddl classpathDir="build/classes" rootPackageName="examples" sqlKeywordCaseType="lowercase" sqlIdentifierCaseType="uppercase" classpathRef="classpath" />
sqlKeywordCaseType属性に"lowercase"とsqlIdentifierCaseType属性に"uppercase"を指定した場合、生成されるSQLは次のようになります。
create table HOGE (AAA varchar(255));
独自のテンプレートファイルを使用する
任意のディレクトリに独自のテンプレートファイルを置き、templateFilePrimaryDir属性にそのディレクトリを指定することで、 独自のテンプレートファイルを使用できます。
S2JDBC-Genのテンプレートは、配布ファイルのsrc/main/resources/org/seasar/extension/jdbc/gen/internal/generator/tempaltesディレクトリ以下にあります。 ここでは、テーブルのcreate文のテンプレートを置き換える例を示します。 テーブルのcreate文のテンプレートトはsql/create-table.ftlです。 修正は、これをコピーして行うと良いでしょう。
テンプレートファイルを格納するディレクトリをmytempletesとする場合、 修正した独自テンプレートを使用するにはテンプレートをmytempletes/sql/create-table.ftlと配置し、templateFilePrimaryDir属性にmytempletesを指定します。
<gen-ddl classpathDir="build/classes" rootPackageName="examples" templateFilePrimaryDir="mytempletes" classpathRef="classpath" />
mytempletes/my-create-table.ftlのように、テンプレートファイルを任意の名前で配置したい場合は、 templateFilePrimaryDir属性に加え、createTableTemplateFileName属性も指定します。
<gen-ddl classpathDir="build/classes" rootPackageName="examples" templateFilePrimaryDir="mytempletes" createTableTemplateFileName="mytempletes/my-create-table.ftl" classpathRef="classpath" />
MySQLでストレージエンジンを指定する
MySQLでストレージエンジンを指定するには、tableOption属性を使用します。 たとえば、ストレージエンジンにINNODBを使用するにはtableOption属性に次のように指定します。
<gen-ddl classpathDir="build/classes" rootPackageName="examples" tableOption="ENGINE = INNODB" classpathRef="classpath" />
上記の定義でGen-Ddlタスクを実行すると次のようなDDLが生成されます。
create table HOGE (AAA varchar(255)) ENGINE = INNODB;
バージョンディレクトリのパターンを指定する
デフォルトでは、バージョン番号に対応するディレクトリの名前はバージョン番号が大きくなるにつれ、0000、0001、0002となります。 バージョン番号の前に0をいくつ付与するかは、versionNoPattern属性で調整できます。
<gen-ddl classpathDir="build/classes" rootPackageName="examples" versionNoPattern="00000000" classpathRef="classpath" />
上記の定義でGen-Ddlタスクを実行すると、バージョン番号に対応するディレクトリの名前はバージョン番号が大きくなるにつれ、00000000、00000001、00000002となります。