[Grails]データベースマイグレーション

#概要

**下書きが溜まってしまったのでとりあえず投稿。そのうち文章とか修正予定。**

Grailsでは開発段階では基本的にDBのテーブルはGrails自信が起動時/終了時にcreate/dropします。
しかし、いざ本番環境で稼働し始めた後や、すでにテストに必要なテストデータが大量に格納されている場合、開発環境の起動時に毎回dropされたりcreateされたりするのは非常に不味いです。

そこで、Grailsに標準で添付されているマイグレーションツールを利用します。
マイグレーションツールを利用することで、データベースのテーブル構造に関す変更の差分のみ（ドメインに完する変項）を、Grailsで管理、適用することが出来るようになります。

なお、今回はPostgreSQLを使って試しています。
実際にコードを実行して試される場合は、GrailsからPostgreSQLにアクセスできるようにしておいてください。

#初回の準備
Grailsのマイグレーションツールは、全てのドメイン/テーブルに関する変更を**changelog**という名前で管理します。
さらに、そのchagnelogの中は**changeSet**という単位で変更の塊を管理しています。
changelogXMLベースで管理するのかGroovyベースで管理するのか決めましょう。
と言っても、変更履歴を管理するファイル名の拡張子を**.groovy**にするか**.xml**にするかの違いだけ。
今回は全てGroovyベースで進めます。

あと、DataSource.groovyの各環境のdataSourceはコメントアウトしておいてください。

ただし、初回実行時の状況によって以下の3パターンが有ります。
##変更を管理するファイルchangelogの作成
###パターン1:ドメインも実際のデータベースもまだ何もない状態。
とても簡単。以下のコマンドのどっちでもいいから実行。

```:テーブルの情報を元にする。
grails dbm-generate-changelog changelog.groovy
```

```:ドメイン（GORM）の情報を元にする。
grails dbm-generate-gorm-changelog changelog.groovy
```

###パターン2:すでに既存のGORMがある場合

```:ドメイン（GORM）の情報を元にする。
grails dbm-generate-gorm-changelog changelog.groovy
```

###パターン3:すでに既存のテーブルがある場合。

```:テーブルの情報を元にする。
grails dbm-generate-changelog changelog.groovy
```


##実行結果
今回は完全に空っぽなパターン1の状態で、とりあえずどっちでもいいのでコマンドを実行します。

```:changelogの作成
grails dbm-generate-changelog changelog.groovy
```

すると、`grails-app/migrations/changelog.groovy`というファイルが生成されます。
パターン1の場合、中身は空っぽです。（以下の通り）

```groovy:grails-app/migrations/changelog.groovy
databaseChangeLog = {
}
```

##マイグレーション用テーブルの生成
`dbm-changelog-sync`というコマンドを実行します。

```:インタラクティブモードで実行
grails> dbm-changelog-sync
| Finished dbm-changelog-sync
grails> 
```
このコマンドによって、PostgreSQLの該当データベースに2つのテーブルが作成されました。

```
dbmigration=# \d
               List of relations
 Schema |         Name          | Type  | Owner 
--------+-----------------------+-------+-------
 public | databasechangelog     | table | koji
 public | databasechangeloglock | table | koji
(2 rows)

```


このコマンドは本来、changelogで管理されている変更を、全て適用済みだよ、と一括処理するためのコマンドです。詳細は最後の方で別途記述します。
この生成された2つのテーブルが、このマイグレーションツールの情報を管理してくれるテーブルです。
今回のパターン1の場合、**databasechangelog**テーブルの中身は今の所空っぽです。
**databasechangeloglock**テーブルの方は1件レコードが有ります。

```
dbmigration=# select * from databasechangeloglock ;
 id | locked | lockgranted | lockedby 
----+--------+-------------+----------
  1 | f      |             | 
(1 row)

```

が、まぁ今の所無視しちゃいましょう。

#準備完了
これで、データベースの変更が安全安心に管理できるようになりました。
念の為確認しましょう。

1. **grails-app/migrations/changelog.groovy**というファイルは有りますか？
2. **databasechangelog**というテーブルがありますか？
3. **databasechangeloglock**というテーブルが有りますか？

この3点がOKなら大丈夫です。
では早速使ってみましょう。

#でもその前に...注意
Grailsのインタラクティブモードでマイグレーション用コマンドを実行すると更新されなかったりして混乱します。
これは、Grailsのインタラクティブモードでドメインのキャッシュなどを保持しているためだと思われます。
以降、`dbm-*`コマンドは全て通常のLinux/Macのコンソールから行うようにしてください。

#実際に試してみる
とりあえず**Person**というドメインを生成してみます。

```:インタラクティブモードでドメインの作成
grails> create-domain-class Person
| Created file grails-app/domain/dbmigration/Person.groovy
| Created file test/unit/dbmigration/PersonSpec.groovy
grails> 
```

Person.groovyの中身を適当に以下のような感じに編集

```groovy:grails-app/domain/dbmigration/Person.groovy
package dbmigration

class Person {

    String name
    Integer age
    static constraints = {
    }
}
```

##差分の記録（dbm-gorm-diff）
現在、当然のことながらドメイン/GORMの内容と実際のテーブルには差分が有りますね。（そもそもテーブルがまだない）
この状態で、マイグレーションツールにこの差分情報を記録してもらいます。
そのために、`dbm-gorm-diff`というコマンドを使います。
以下のような感じです。

```
grails dbm-gorm-diff 2014-11-14-person-added.groovy --add
```

すると、引数で指定したファイル名が、**grails-app/migrations/2014-11-14-person-added.groovy**として保存されます。
そのファイルの中に、実際のGORMとデータベースの差分が書き込まれます。
また、初回に作成した**grails-app/migrations/changelog.groovy**に、このファイルのinclude文が追記されます。

##差分の適用（dbm-update）
それでは引き続き`grails dbm-update`というコマンドを事項してみてください。

```
grails dbm-update
```

エラーなくコマンドが終了したら、実際にデータベースを確認してみましょう。
なんと！ちゃんとpersonテーブルが生成されていますね！

すでにこの変更（2014-11-14-person-added.groovy）は適用されたとちゃんと記憶されているので、今後何度`grails dbm-update`を実行しても再実行されることはありません。
この情報の管理先が、最初に生成した**databasechangelog**テーブルです。

##デプロイ
本番環境にアプリケーションをデプロイする場合、データベースの変更はどうなるんでしょうか？
通常のWEBアプリケーションではプログラムのデプロイと、テーブルに対する変更を別々に行う必要が有ります。
しかしGrailsのdbmigrationプラグインはそれらを自動化してくれます。

まず、`grails-app/conf/Config.groovy`の末尾に

```groovy:grails-app/conf/Config.groovy
grails.plugin.databasemigration. updateOnStart = true
grails.plugin.databasemigration. updateOnStartFileNames = ['changelog.groovy']
```
を追記します。
そしてwarを生成します。

```:普通にwarを生成
grails war
```

これでTomcatなどのサーブレットコンテナにwarを適切にデプロイすれば自動的に本番データベースのテーブルの変更までdbmigrationが自動で行ってくれます！便利！


##軽いまとめ
今後、実際に運用を進めていく場合は、

1. ドメイン/GORMの修正
2. `db-gorm-diff`コマンドで差分の記録
3. `db-update`コマンドで差分をデータベースに適用
4. しっかりテストする。
5. 1から4を必要な分繰り返した後、本番にデプロイする

の繰り返しです。
とても簡単ですね！

#dbm-gorm-diffで--addを忘れちゃった！
`dbm-gorm-diff`コマンドで、`--add`オプションを付けずに実行すると、単純に生成されたファイル名がデフォルトの**changelog.groovyの中でincludeされません。**
そんな状態で`dbm-update`を実行しても、マイグレーションツールはchangelog.groovyの中身を元に必要はファイルを検索しているので、当然何も変化しません。
そんなどうすればいいんだ。。。。
大丈夫。指定した名前（差分のGroovyファイル）は普通に作成されているはずなので、単純にchangelog.groovyの、include文が追記されていっている部分の末尾に、そのファイルのinclude文を追記してあげましょう。
その後、再度`grails dbm-upate`を実行すればちゃんと動きます。


#開発環境のDBから、テスト用のデータベースを作成する。
超簡単。
まずは当然Datasource.groovyから、テストDB用のサーバ、データベースに接続できるようにしておく。
完了したら後は`grails test dbm-update`と実行するだけ。
データベースマイグレーションで管理されている情報（つまりgrails-app/migrations/changelog.groovy）を元に、まだテスト用データベースに適用されていない全ての変更が実行されます。
後はテスト用のデータをテスト用に登録するだけ。

#テーブルから変更する。
似て非なるもの？な感じのする`dbm-diff`というコマンドがあります。
コレはもうドメイン（GORM）は関係ありません。
単純に、ある実行環境と、ある別の実行環境の間でテーブルに差分があるかどうかを確認/記録するためのものです。
例えば開発（デフォルトのdev）とテスト（test）のテーブル間で差分があるかどうか確認できます。

ではまず、開発環境のperosnテーブルにSQLでカラムを追加してみる。

```
dbmigration=# ALTER TABLE person ADD add_from_pgsql varchar(255);
ALTER TABLE
dbmigration=# 
dbmigration=# select * from person;
 id | version | age | name | add_from_pgsql 
----+---------+-----+------+----------------
(0 rows)
```

追加できました。
すでにテスト環境のデータベースを上で作成していますので、それとこの開発環境のデータベースを`dbm-diff`を使って比べてみます。

`grails dev dbm-diff test`とういコマンドを時刻した場合の実行結果は以下のとおりです。（見やすいように余分な部分を削除しています。）
余談ですが、`dbm-diff`でも`dbm-gorm-diff`でも、出力するファイル名を指定しない場合、XMLとしてコンソールに表示されます。どういった内容の差分があるのか確認したいだけの時に便利です。

```xml:grails&nbsp;dev&nbsp;dbm-diff&nbsp;testの実行結果
<changeSet author="k-kuwana (generated)" id="1415977568511-1">
    <addColumn tableName="person">
        <column name="add_from_pgsql" type="VARCHAR(255)"/>
    </addColumn>
</changeSet>
```

今度は試しに実行環境の指定を反対にして`grails test dbm-diff dev`としてみます。

```xml:grails&nbsp;test&nbsp;dbm-diff&nbsp;devの実行結果
<changeSet author="k-kuwana (generated)" id="1415977601826-1">
    <dropColumn columnName="add_from_pgsql" tableName="person"/>
</changeSet>

```

それぞれ差分がちゃんと表示されていますね。
このことから、最初に指定する環境から見て、2個めに指定する環境のテーブルがどうなっているか、という条件になっていることがわかります。

では、開発環境が正のものとして進めましょう。
当然diffの結果を保存する必要が有ります。

```:diffの結果を保存（--addオプションを忘れずに）
grails dev dbm-diff test sqlbaseadded.groovy --add
```
と実行して、

```:変更を適用
grails test dbm-update
```
と実行します。

テストデータベースのperseonテーブルを確認してみます。

```
dbmigrationtest=# select * from person;
 id | version | age | name | add_from_pgsql 
----+---------+-----+------+----------------
(0 rows)
```
ちゃんと開発用のデータベースにSQLベースで追加したカラムがテスト環境の方にも適用されましたね。

###ここで注意！！！
今後作業を続けて行く前に注意です。
テスト環境に対してはマイグレーションを実行したのですでに最新のものになっていますが、開発環境はどうでしょう？
テーブルが新しくなっていて、マイグレーションツールはそのための差分（ADD COLUMNSのSQL）を保持しています。
**しかし開発環境用のマイグレーション用テーブルにはその事実が記録されていません。**
だってそもそも開発環境向けにはまだ`dbm-update`を実行していないので。
じゃあ実行してみましょう。

```:dbm-upateの実行をすると。。。？
kkuwana% grails dbm-update

| Starting dbm-update for database koji @ jdbc:postgresql://127.0.0.1:5432/dbmigration
| Error 2014-11-14 16:32:10,991 [main] ERROR liquibase  - Change Set sqlbaseadded.groovy::1415978760219-1::k-kuwana (generated) failed.  Error: Error executing SQL ALTER TABLE person ADD add_from_pgsql VARCHAR(255): ERROR: column "add_from_pgsql" of relation "person" already exists
Message: Error executing SQL ALTER TABLE person ADD add_from_pgsql VARCHAR(255): ERROR: column "add_from_pgsql" of relation "person" already exists
以下省略
```
なんかエラーが出てしまいます。
というのは、まだマイグレーション用テーブルに、今回生成した**sqlbaseadded.groovy**が実行されたよ、というログが存在していないため、`dbm-update`は当然このファイルを実行しようとします。
でもそもそも開発環境用のpersonテーブルに対してSQLでカラムを追加しているので、当然すでに同名のカラムがあるよ、というエラーが表示されているわけですね。

このままだと、今後どんなに変更をしていったとしてもこのエラーのせいでdbm-updateを実行することが出来ません。
じゃどうするんだ！とう言うことで、初回に1回だけ実行した`dbm-changelog-sync`を実行します。
すると、changelog.groovyでincludeされているファイルの中で、まだ実行されていない物がある場合には、**実際には実行せずに、実行済みだよ、とマークしてくれます。**

実際に実行してみましょう。
`grails dev dbm-changelog-sync`
で、再度`dbm-update`を試してみます。
`grails dev dbm-update`
エラーが出ずに終了しましたね。

*混乱を避けるため、grailsコマンドの後に明示的に環境（dev）を指定していますが、省略すればデフォルトでdev環境になるので、今回の場合であれば省略してもOKです。


#dbm-changelog-syncの正体
さて、マイグレーションツールは、全ての変更を**changelog.groovyで管理しています。**
そして、その変更（changelog.groovyの中身）が、データベースに対して実行されたかどうかは**databasechangelog**テーブルが管理しています。

`dbm-changelog-sync`コマンドは、changelog.groovyで管理されている変更のうち、まだ実行されていない変更を、単純に**databasechangelog**テーブルに実行済み、としてINSERTします。
やっていることは本当にコレだけです。
このテーブルに実行済みとしてレコードが格納されているので、次回以降`dbm-update`を実行しても、すでに適用された差分が再度適用されることが防げているわけですね。

このあたりを意識する必要があるのは、GORMの変更ではなくて、さっき試したテーブルを直接SQLで修正する場合のみかなと思います。
でも、データベースの取り扱いに関する重要なこのツールの動作を理解しないまま使うのはやっぱり怖いので、軽くでもこのあたりの動作を把握しておいたほうが精神衛生上宜しいと思います。

###もし誤って`dbm-changelog-sync`を実行してしまった場合
`grails dbm-gorm-diff`か`grails dbm-diff`で、変更履歴を作成したあとに、`dbm-update`を実行せずに間違って`dbm-changelog-sync`を実行すると、まだデータベースに反映していないので、上述の通り、時刻済みとして**databasechangelog**テーブルにレコードが格納されてしまいます。

もしそうしてしまった場合は、`grails dbm-gorm-diff`で追加したファイル名を元に、**databasechangelog**テーブルからそのレコードを削除して、再度`dbm-update`を実行すればOKです。





#実際に運用する場合

とりあえずは全てcreate-dropモードで開発していく。
で、テーブルの作成、変更が落ち着いた段階（初回リリース時など）以降、dbmigrationを使ってデータベースの構造に完する変項を管理、適用していく。
このタイミングで、DataSource.groovyのdev、test、prodの前環境で、**dbCreate**をコメントアウトしておく。
今後データベースに対する変更は全てdbmigration経由で行うためです。

##ドメインあり、テーブルなし状態。
初回の準備の中で書いたパターン2です。
現在開発段階で、ずっとcreate-dropモードで開発してきており、テーブル自体はデータベース上に存在していなくて、GORM/ドメインのみが存在持している状態。

dbmigrationで管理を始めるには、初回に以下のコマンドを実行してchangelog.groovyを作成します。

```
grails dbm-generate-gorm-changelog changelog.groovy
```
とすると、changelog.groovyの中にそのままベタでchangeSetが記述されます。
すでにデータベースとドメインの間に差分があるためですね。
この状態で

```
dbm-update
```
すれば当然通常通り変更が適用できます。

**あれ？上の方で初回の作業時にdbm-changelog-syncって実行してなかったっけ？**と思った人は記憶力と理解力のずば抜けている人です！

`dbm-generate-gorm-changelog changelog.grooy`を実行した後に、`dbm-changelog-sync`を実行すると、当然changelog.groovyの中に記述された差分が適用済みとして、`databasechangelog`の中に登録されてしまうのです。
ドメインもテーブルも空っぽの状況ならコレでなんの問題もありませんでしたが、今回はドメインは完成しているものがすでにあるけど、テーブルが空っぽだから、この差分が適用されなければ困りますね。

なので、今回のような**ドメイン有り、テーブルなし**な場合は

1. `grails dbm-generate-gorm-changelog changelog.groovy`
2. `grails dbm-update`

と素直に実行してあげる必要が有ります。

ちなみに、dbm-updateコマンドも、データベース上に**databasechangelog**と**databasechangeloglock**というマイグレーション用テーブルがない場合は自動的に生成してくれます。

なんかchangelog.groovyの中にいきなり差分が書かれるのは気持ち悪い。。。差分はあくまでchangesetフィル（dbm-gorm-diffで作成するファイル）の中でのみ管理したい。。。という場合、現在**ドメイン有り、テーブルなし**なので、テーブルの情報からchangelogを作成して、`dbm-gorm-diff`で差分ファイルを作成->`dbm-update`という流れで実現できます。

1. `grails dbm-generate-changelog changelog.groovy`
2. `grails dbm-gorm-diff initial_create_tables_from_gorm.groovy --add`
3. `grails dbm-update`

1を実行すればからのchangelog.groovyが作成されて、2を実行すればinitial_create_tables_from_gorm.groovyに差分が記述されて、さらにこのファイルのinclude文がchangelog.groovyに自動的に追記されます。
最後の3番の実行で、差分がデータベースに適用されます。


##ドメインなし、テーブルあり状態。
今度は逆にドメインはまだないけど、テーブル自体はすでに作成されているという状態です。
どんな時にこんな状態になるかというと、例えばすでに稼働しているシステムがあって、データベースはそのままで、Grailsで新しいガワを作りたい、といった感じでしょうか。

このパターンはちょっと分かり辛いですが、基本的には

1. `grails dbm-generate-changelog changelog.groovy`
2. `grails dbm-changelog-sync`

と実行します。
1でまずテーブル情報をそのままchangelog.groovyに差分として書き出しますが、そもそもGrailsアプリケーション側にはドメインが存在していないし、テーブル自体の情報を取得して差分としてchange.logに書き出しているので、ワザワザ`dbm-update`を実行する必要はありません。
というよりも、すでにテーブルが正として存在しているので、`dbm-update`を実行してもエラーになります。

**テーブル自体の変更をドメインに反映する方法はありませんので、手動でドメインを修正していきます。**





#その他整理のためのちょっとメモ
databasechangelogテーブルは、changesetの単位でレコードが増えていく。
そのため、同じfilenameが連続して格納されることもある。なのでそれは問題じゃない。


#まとめ
だらだらと書いてしまいました。
Grailsの開発段階では、dbCreateをdrop-createにしてバリバリ開発していけばいいのですが、いざ本番リリース後には当然バージョンアップ、修正を重ねていく必要が有ります。
dbmigrationプラグインを使えば、プログラムの修正を本番に反映（warのデプロイ）、データベースの変更をSQLで反映といった作業を分けて行う必要はなくなりますし、変更の内容などは全てdbmigrationプラグインが管理してくれているので、作業漏れなどが減らせます。

留意する点としては、基本的にはGrails側からdbmigrationプラグインを通して全てのテーブルの変更を実行するようにしたほうがいいという点です。
もし別の環境（例えばいきなり本番DB）でテーブルの構造を変更した場合には、以下のような手順を踏む必要が有り、かなり煩雑な作業が必要になります。

1. 何らかの方法で、開発環境のGrails経由で新しいテーブルの構造を持つデータベースに接続できるようにする。
2. `grails 例えばprod dbm-diff dev sqlbaseadded.groovy --add`を実行。
3. `grails dbm-update`を実行。
4. `grails 例えばprod dbm-changelog-sync`を実行。
5. 環境によるが、最初にアクセスできるようにした環境をセキュリティの観点から開発環境からはアクセスできないように元に戻す。
6. 終了

特に4番の作業を忘れると、いざデプロイしたらアプリケーションが起動しないなどの問題が発生します。（Grails起動時にdbmigrationを自動実行するようにしている場合）

いずれにせよ、データベースの変更というのは大変な作業ですし、開発ルール、運用ルールは会社、プロジェクト、人、環境によって様々です。
まずは実際にテストプロジェクトでdbmigrationプラグインを触ってみて、自分の環境に適した運用ルール、使い方を見つけていきましょう。

なお、今回は触れていませんが、データ自体の登録もdbmigrationツールで簡単かつ安心便利に行うことが出来ます。それについてはまた別途。



#参考
[公式ドキュメント](http://grails-plugins.github.io/grails-database-migration/docs/manual/guide/)
[Database Migration Pluginがすごい ~入門編~](http://yamkazu.hatenablog.com/entry/2012/10/27/201519)
[Database Migration Pluginがすごい ~ロールバック編~](http://yamkazu.hatenablog.com/entry/2012/10/28/175001)
[dbm-gorm-diff](http://grails-plugins.github.io/grails-database-migration/docs/manual/ref/Diff%20Scripts/dbm-gorm-diff.html)
[dbm-diff](http://grails-plugins.github.io/grails-database-migration/docs/manual/ref/Diff%20Scripts/dbm-diff.html)
[dbm-changelog-sync](http://grails-plugins.github.io/grails-database-migration/docs/manual/ref/Maintenance%20Scripts/dbm-changelog-sync.html)
[dbm-update](http://grails-plugins.github.io/grails-database-migration/docs/manual/ref/Update%20Scripts/dbm-update.html)