The Seasar Project

概要

エンティティクラスのメタデータを読み取り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
    │     └─050-auxiliary
    ├─0001
    │  ├─create
    │  │  ├─010-table
    │  │  ├─020-uniquekey
    │  │  ├─030-sequence
    │  │  ├─040-dump
    │  │  ├─050-foreignkey
    │  │  └─060-auxiliary
    │  └─drop
    │     ├─010-foreignkey
    │     ├─020-sequence
    │     ├─030-uniquekey
    │     ├─040-table
    │     └─050-auxiliary
    └─0002
        ├─create
        │  ├─010-table
        │  ├─020-uniquekey
        │  ├─030-sequence
        │  ├─040-dump
        │  ├─050-foreignkey
        │  └─060-auxiliary
        └─drop
           ├─010-foreignkey
           ├─020-sequence
           ├─030-uniquekey
           ├─040-table
           └─050-auxiliary

db/migrateディレクトリ以下の、0000、0001、0002はDDLのバージョンを表すディレクトリです。 バージョンを表すディレクトリは、Gen-Ddlタスクを実行するごとに新しく作成されます。

バージョンを表すディレクトリの下にはcreateディレクトリとdropディレクトリがあります。 createディレクトリでは、データベースオブジェクトの作成用DDLとダンプデータを管理し、 dropディレクトリでは、データベースオブジェクトの削除用DDLを管理します。

createディレクトリとdropディレクトリの下には、各オブジェクト専用のDDLもしくはダンプデータを管理するためのディレクトリがあります。

バージョン番号

DDLのバージョン番号は、ddlInfoFile属性に指定したテキストファイルで管理されます。 バージョン番号は0から始まり、上限の2147483647まで1ずつ増分します。 バージョン番号を管理するテキストファイルは、番号を振り直すなどの特別な理由がない限り編集しないでください。

DDLファイル

エンティティクラスの定義からDDLファイルが出力されます。 どのようなエンティティ定義からどのようなDDLを生成できるかは、DDL生成のためのエンティティ定義 を参照してください。

Gen-Ddlタスクでサポートしていないストアドプロシージャー、トリガー、ビューなどのDDLを扱うには、Migrateタスクの任意のSQLの実行 を参照してください。

出力先のディレクトリはパラメータにより変更できます。

生成されるファイルの形式は、SQLファイル と同様です。

ダンプファイル

dump属性が"true"の場合、データベースのデータがCSV形式でダンプ出力されます。

出力先のディレクトリはパラメータにより変更できます。

出力されるデータの形式は、ダンプファイル の説明を参照してください。

タスク実行時のファイルのコピー

Gen-Ddlタスクは、DDLやダンプデータを生成後、生成対象外かつ前バージョンのディレクトリに含まれるファイルを新しいバージョンのディレクトリにコピーします。 この仕組みにより、Gen-Ddlで生成される以外のファイルをGen-Ddlで生成されるファイルと同様の方法で管理できます。

たとえば、バージョン0002のcreateディレクトリの下に061-procedureや062-view、dropディレクトリの下に001-viewや002-procedureといったディレクトリを作成し、そこにストアドプロシージャーやビューの作成用DDLと削除用DDLファイルを置くとします。

db
└─migrate
    └─0002
        ├─create
        │  ├─010-table
        │  ├─020-uniquekey
        │  ├─030-sequence
        │  ├─040-dump
        │  ├─050-foreignkey
        │  ├─060-auxiliary
        │  ├─061-procedure
        │  └─062-view
        └─drop
           ├─001-view
           ├─002-procedure
           ├─010-foreignkey
           ├─020-sequence
           ├─030-uniquekey
           ├─040-table
           └─050-auxiliary

Gen-Ddlタスクを実行すると、これらはバージョン0003のcreateディレクトリやdropディレクトリ以下にそのままコピーされます。

トップレベルのパラメータ

ネストした要素として指定されるパラメータ

jvmArg

このタスクの大部分の処理は別VMで行われます。VMに引数を渡す場合は<jvmarg>要素を使用します。 これはAntのJavaタスクで使用できる<jvmarg>と同じです。 使用可能な属性やネストした要素についてはAntのドキュメントを参照してください。

SQLのキーワードと識別子の大文字小文字を指定する

sqlKeywordCase属性とsqlIdentifierCase属性に"uppercase"や"lowercase"といった値を指定することで、SQLのキーワード（CREATEやALTERなど）やSQLの識別子（テーブル名やカラム名）の大文字小文字を指定できます。 たとえば、次のように指定できます。

<gen-ddl
    classpathDir="build/classes"
    rootPackageName="examples"
    sqlKeywordCase="lowercase"
    sqlIdentifierCase="uppercase"
    classpathRef="classpath"
/>

sqlKeywordCase属性に"lowercase"とsqlIdentifierCase属性に"uppercase"を指定した場合、生成されるSQLは次のようになります。

create table HOGE (AAA varchar(255));

逆に、sqlKeywordCase属性に"uppercase"とsqlIdentifierCase属性に"lowercase"を指定した場合、生成されるSQLは次のようになります。

CREATE TABLE hoge (aaa VARCHAR(255));

独自のテンプレートファイルを使用する

任意のディレクトリに独自のテンプレートファイルを置き、templateFilePrimaryDir属性にそのディレクトリを指定することで、 独自のテンプレートファイルを使用できます。

S2JDBC-Genのテンプレートは、配布ファイルのresources/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="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となります。

DDLを生成する理由を記録する

DDLを生成する理由（エンティティの変更内容）をcomment属性に記述しddlInfoFile属性で指定されたファイルに記録できます。 AntのInputタスクと組み合わせて使用すると良いでしょう。

<input
    message="DDLを生成する理由（エンティティの変更内容）を入力してください。"
    addproperty="gen-ddl.comment"
/>
<gen-ddl
    classpathDir="build/classes"
    rootPackageName="examples"
    comment="${gen-ddl.comment}"
    classpathRef="classpath"
/>

上記の定義を利用すると、コンソールからの入力をコメントとして使用できます。

エンティティのJavaDocコメントをテーブル作成用のDDLファイルに反映させる

エンティティのJavaDocコメントをDDLに反映させるには、applyJavaCommentToDdl属性に"true"を指定します。 また、必要に応じてjavaFileSrcDirs属性とjavaFileEncoding属性を使用します。 javaFileSrcDirs属性については、カンマや空白区切りで複数の値を指定できることに注意してください。

<gen-ddl
    classpathDir="build/classes"
    rootPackageName="examples"
    applyJavaCommentToDdl="true"
    javaFileSrcDirs="src1, src2"
    javaFileEncoding="MS932"
    classpathRef="classpath"
/>

この機能では、Docletを使用してソースコード上のコメントを読み取るため、クラスパスにJDKのtools.jarが指定されている必要があります。 コメントに対応していないRDBMSでは、applyJavaCommentToDdl属性に"true"を指定しても、JavaDocコメントはDDLに反映されません。

外部キー制約の自動生成を無効化する

デフォルトでは、関連プロパティに対応するカラムが外部キーとみなされDDLが自動生成されます。 これを無効にするには、autoGenerateForeignKey属性に"false"を設定します。

<gen-ddl
    classpathDir="build/classes"
    rootPackageName="examples"
    autoGenerateForeignKey="false"
    classpathRef="classpath"
/>

上の定義を利用すると、外部キー制約のDDLが自動生成されなくなります。

autoGenerateForeignKey属性は、全てのエンティティを対象とし、一括で自動生成の有効/無効を制御する場合に使用します。 関連プロパティごとに外部キー制約の生成を制御するには、 外部キー定義 を参照してください。