Doctrineのmigration機能でデータベーススキーマの差分管理

symfony Doctrine

DoctrineにはRuby on Rails由来のmigration機能があります。
この機能を今まで使っていなかったので、ちょっと調べてみました。

なお、参考ドキュメントは以下ですが、このドキュメントを読むだけでは細かい挙動を把握できませんでした。

コマンド

migrationクラスとは？

migrationクラスには、up()とdown()メソッドがあり、それぞれ「次のバージョンへスキーマを変更する」「前のバージョンにスキーマを戻す」操作を記述します。
手作業でmigrationクラスを作って管理することもできますが、Doctrineでは自動的にmigrationクラスを生成する機能があります。

php symfony doctrine:generate-migrations-db

このコマンドでは、「現在のデータベースのスキーマ（旧）」と、「YAMLスキーマファイルのスキーマ（新）」を比較して、差分をmigrationクラスとして出力します。

php symfony doctrine:generate-migrations-models

このコマンドは、現在のモデルをすべてゼロから生成するmigrationクラス群を出力します。差分ではないことに注意が必要です。

php symfony doctrine:generate-migrations-diff

このコマンドは、「現在のモデルクラス（旧）」と、「YAMLスキーマファイルのスキーマ（新）」を比較して、差分をmigrationクラスとして出力します。

実際のケース

実際の開発において、データベースの差分管理を行う具体的な方法は以下のような感じです。

  1. 最初のスキーマをYAMLファイルに定義し、これに対応するモデルクラスを生成する
    1. ある程度FIXした状態のものを想定。これをバージョン1とします。
    2. 開発現場によっては、YAMLスキーマ主体ではなく、DB側主体の場合もあるかと思います。この場合でも、DBからYAML生成→モデル生成を行って下さい。
    3. 「php symfony doctrine:generate-migrations-models」を実行します。
      1. 最初のmigrationクラス群が/lib/migration/doctrineディレクトリに生成されます。
    4. データベースを一度削除します。（php symfony doctrine:drop-db）
    5. データベースを再作成します。（php symfony doctrine:build-db）
    6. 最初のマイグレーションを実行します。（php symfony doctrine:migrate）
      1. このコマンド実行後、データベースが最初のスキーマの状態になっています。
      2. 同時に、マイグレーションバージョン管理用のテーブル（migration_version）がDB内に作成され、バージョン番号（1）が設定されます。
  2. スキーマを更新します。
    1. YAMLスキーマ主体でスキーマを管理している場合は、YAMLファイルのみを更新します。
    2. DB主体でスキーマを管理している場合は、DBを変更後、doctrine:build-schemaを実行してYAMLスキーマファイルを更新します。このとき、モデルを更新しないように注意してください。
  3. 差分migrationを生成する
    1. 「php symfony doctrine:generate-migrations-diff」を実行すると、現在のモデルクラスと新しいスキーマファイルとの差分がmigrationクラスとして出力されます。
  4. migrationをDBに適用する
    1. 「php symfony doctrine:migrate」を実行すると、出力したmigrationの内容がDBに適用されます。
      1. モデルクラスやフォームクラスは更新されないので、「doctrine:build --model --forms」を実行する。


ポイントは最初にmigration対応にする（migration_versionテーブルの作成）ことです。