テーブル作成

• 処理概要
• 実行ファイルの仕様
  • 実行ファイルの規約
  • 実行順序
  • エンコーディング
• SQLの仕様
  • SQLのデリミタ
  • SQLの範囲の明示的指定
  • 定義するSQL
  • エラーハンドリング
  • トランザクション
  • 改行の扱い
• 変数のフィルタ
• システムユーザでの実行
• 環境ごとの実行チェック
  • checkEnv()コメント
  • checkEnvの途中定義
  • 環境タイプの複数指定
  • 主にはシステムユーザで

処理概要

DBFluteプロパティ databaseInfoMap.dfprop に定義されたスキーマに接続し、仕様に合致するファイルに定義されているDDL文を実行します。

実行ファイルの仕様

実行ファイルの規約

以下の全ての条件に合致するテキストファイルが実行対象：

• "DBFluteクライアント]/playsql" 配下のファイル
• ファイル名が "replace-schema" で始まる
• ファイル名が ".sql" で終わる

条件で定められている部分以外のファイル名は任意の文字列となります。基本的にはそのSQLファイルの役割を表現するようにします。また、replace-schema.sql という名前のファイルも実行対象となります。

e.g. テーブル作成のSQLファイル @DBFluteClient
playsql
 |-replace-schema-basic.sql
 |-replace-schema-sequence.sql
 |-replace-schema-view.sql
 |-...

実行順序

実行する順序は、拡張子を含めたファイル名の辞書順(昇順) で実行します。実行順序を明確にしておくために、習慣的に 番号で管理 しておくことをお奨めします。

e.g. テーブル作成のSQLファイルで番号管理 @DBFluteClient
playsql
 |-replace-schema-10-basic.sql
 |-replace-schema-20-view.sql
 |-replace-schema-30-sequence.sql
 |-...

エンコーディング

エンコーディングは "UTF-8" として扱われます。別のエンコーディングを利用したい場合は、オプションで変更可能です。

SQLの仕様

SQLのデリミタ

一つのファイル内に複数のSQLを定義できます。デリミタは ";" (セミコロン) とし、読み込まれた順序で実行していきます。

e.g. SQLのデリミタ @SQL-File
create table MEMBER ...
;
create table PURCHASE ...
;
...

SQLの範囲の明示的指定

但し、プロシージャなどデリミタが ";" だと都合の悪いことがあります。その場合は、ある範囲を一つのSQLとして明示的に指定することが可能です。

SQLコメントで "-- #df:begin#" を開始とし、"-- #df:end#" を終了として、一つのSQLを囲みます。この中にデリミタ文字が含まれていても、それはSQLの一部とみなされます。

e.g. SQLの範囲を明示的に指定 @SQL-File for Oracle
-- #df:begin#
create or replace procedure SP_NO_PARAMETER
as
begin
  dbms_output.put_line('aaa');
end SP_NO_PARAMETER;
/
-- #df:end#

-- #df:begin#
create or replace procedure SP_IN_OUT_PARAMETER(
...
-- #df:end#

定義するSQL

ここではDDL文が定義されていることを想定していますが、実際にはDML文と区別をして実行しているわけではないので、 insert文やupdate文が定義されている場合にそのまま実行されます。但し、ほとんどの場合においてDML文をここで実行する必要性はないと想定しています。 (例えば、データの登録は "ReplaceSchemaのデータ登録" の機能を利用)

エラーハンドリング

どれかのSQLがエラーになった瞬間にタスクは中断します(@since 0.9.9.3C)。

ただし、replaceSchemaDefinitionMap.dfprop にて isErrorSqlContinue を true にすると、 SQLがエラーになっても処理を続行させることができます。 ただそのときでも、ReplaceSchema タスクの "タスク実行ステータス" は "失敗" となり、コンソールの最後には BUILD FAILED と表示されます(@since 0.9.7.9)。 基本的には、やはりSQLのエラーはタスクの失敗という扱いであり、どうしても落ちても仕方のないDDLがあるような状況のためのオプションです。

トランザクション

これらの処理は全て "オートコミットモード" で実行されます。ただ、基本的にDDL文を想定しているのでトランザクションの有無はそもそも無関係です。

改行の扱い

SQL上の改行は、実行時には空白として扱われます。但し、"SQLの範囲の明示的指定" を利用した場合や、"comment on" 構文(DBMSごとに異なる)を利用した場合は、そのまま改行が保持されます。実行ログに実際にDBに発行したSQLが出力されます。

変数のフィルタ

SQL上の値が環境によって変わるような場合は、"replaceSchemaDefinitionMap.dfprop" の "filterVariablesMap" を利用して、SQLファイル上は変数で扱い実際の値を環境ごとに切り替えられるDBFluteプロパティで管理します。

e.g. filterVariablesMapの定義 @replaceSchemaDefinitionMap.dfprop
; filterVariablesMap = map:{
    ; mainSchema   = EXAMPLEDB
}

"filterVariablesMap" で定義した値は、SQLファイル上で "/*$[variable-name]*/" という形式で指定します。実行時にフィルタされて、実際の値に置き換えられます。

filterVariablesMap の値ではなく、databaseInfoMap.dfprop の情報を直接参照したい場合は、"dfprop.xxx" という形式で指定することで利用できます(@since 0.9.8.3)。

e.g. filterVariablesMapを利用したSQL @replace-schema-xxx.sql
create user /*$mainSchema*/.MEMBER ...

このようにDBFluteプロパティで環境依存の値を管理し、"環境タイプによる切り替え" を利用して環境ごとに違う値で実行できるようにします。

システムユーザでの実行

一部のDDLをシステムユーザで実行することができ、DBユーザ自体の作成を自動化できます。

環境ごとの実行チェック

checkEnv()コメント

環境ごとに実行するDDLファイルを切り替えることができます。 DDLファイルの中(基本的には先頭行)で -- #df:checkEnv([env-type])# というように指定すると、そのDDLファイルは指定された環境タイプのときのみ実行されます。 この環境タイプは、replaceSchemaDefinitionMap.dfprop の repsEnvType の値となります。

e.g. "ut" のときだけ実行されるDDLファイル @replace-schema-xxx.sql
-- #df:checkEnv(ut)#

create table ...;

checkEnvの途中定義

基本的には先頭行に定義されることが前提となりますが、途中で定義した場合で該当の環境タイプではなかったら、 その定義を含んでいるSQLを含めてそれ以降の(そのDDLファイル内の)SQLが実行されなくなります。

e.g. "ut" のときだけ実行されるDDLファイル @replace-schema-xxx.sql
-- 常に実行される
create table ...;
create table ...;

-- #df:checkEnv(ut)#
-- これ以降 ut じゃなければ実行されない
create table ...;
create table ...;
create table ...;
create table ...;

環境タイプの複数指定

環境タイプは複数指定もできます。

e.g. "ut" と "it" のときだけ実行されるDDLファイル @replace-schema-xxx.sql
-- #df:checkEnv(ut, it)#

create table ...;

主にはシステムユーザで

主には、システムユーザで実行するDDLにおいて利用されることを想定しています。

サブスキーマのテーブルdrop

メインユーザがアクセスできる範囲のサブスキーマのテーブルdrop処理を実行することが可能です。

"replaceSchemaDefinitionMap.dfprop" の "additionalDropMapList" にて細かく定義できます。

但し、サブスキーマに関してはサブスキーマ側で "ReplaceSchema" 環境を構築して(DBFluteクライアントをもう一つ用意して)構成管理をする方が管理しやすいため、この機能の利用はあまりお奨めではありません。

SiteMap Author's BlogBTS