移行Migrations

データ モデルは開発中に変更され、データベースと同期しなくなります。A data model changes during development and gets out of sync with the database. データベースを削除して、モデルと一致する新しいものを EF に作成させることもできますが、この手順ではデータが失われてしまいます。You can drop the database and let EF create a new one that matches the model, but this procedure results in the loss of data. EF Core の移行機能では、データベースの既存のデータを維持しながら、アプリケーションのデータ モデルとデータベース スキーマを同期した状態で、データベース スキーマを増分的に更新することができます。The migrations feature in EF Core provides a way to incrementally update the database schema to keep it in sync with the application's data model while preserving existing data in the database.

移行には、次のタスクの助けとなるコマンドライン ツールと API が含まれています。Migrations includes command-line tools and APIs that help with the following tasks:

ツールのインストールInstall the tools

コマンドライン ツールをインストールします。Install the command-line tools:

移行を作成するCreate a migration

最初のモデルを定義したら、次にデータベースを作成します。After you've defined your initial model, it's time to create the database. 最初の移行を追加するには、次のコマンドを実行します。To add an initial migration, run the following command.

Add-Migration InitialCreate
dotnet ef migrations add InitialCreate

[移行] ディレクトリの下で 3 つのファイルがプロジェクトに追加されます。Three files are added to your project under the Migrations directory:

  • XXXXXXXXXXXXXX_InitialCreate.cs--メインの移行ファイル。XXXXXXXXXXXXXX_InitialCreate.cs--The main migrations file. (Up() で) 移行を適用し、(Down() で) それを元に戻すために必要な操作が含まれます。Contains the operations necessary to apply the migration (in Up()) and to revert it (in Down()).
  • XXXXXXXXXXXXXX_InitialCreate.Designer.cs--移行メタデータ ファイル。XXXXXXXXXXXXXX_InitialCreate.Designer.cs--The migrations metadata file. EF によって使用される情報が含まれます。Contains information used by EF.
  • MyContextModelSnapshot.cs--現在のモデルのスナップショット。MyContextModelSnapshot.cs--A snapshot of your current model. 次の移行を追加するときの変更内容の決定に使用されます。Used to determine what changed when adding the next migration.

変更の進行がわかるように、ファイル名のタイムスタンプは時系列順で維持されます。The timestamp in the filename helps keep them ordered chronologically so you can see the progression of changes.

ヒント

移行ファイルは自由に移動したり、その名前空間を変更したりできます。You are free to move Migrations files and change their namespace. 新しい移行は前回の移行の兄弟として作成されます。New migrations are created as siblings of the last migration.

データベースを更新するUpdate the database

次に、移行をデータベースに適用し、スキーマを作成します。Next, apply the migration to the database to create the schema.

Update-Database
dotnet ef database update

移行コードをカスタマイズするCustomize migration code

EF Core モデルの変更後、データベース スキーマは同期していない状態になります。それを最新の状態にするには、別の移行を追加します。After making changes to your EF Core model, the database schema might be out of sync. To bring it up to date, add another migration. 移行名は、バージョン管理システムのコミット メッセージのように使用できます。The migration name can be used like a commit message in a version control system. たとえば、変更するのがレビュー用の新しいエンティティ クラスである場合、AddProductReviews などの名前を選択します。For example, you might choose a name like AddProductReviews if the change is a new entity class for reviews.

Add-Migration AddProductReviews
dotnet ef migrations add AddProductReviews

移行が (それのためにコードが生成され) スキャフォールディングされたら、コードが正しいか確認し、それを正しく適用するために必要な任意の操作を追加、削除または変更します。Once the migration is scaffolded (code generated for it), review the code for accuracy and add, remove or modify any operations required to apply it correctly.

たとえば、移行には次の操作が含まれることがあります。For example, a migration might contain the following operations:

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

migrationBuilder.AddColumn<string>(
    name: "Name",
    table: "Customer",
    nullable: true);

これらの操作はデータベース スキーマに互換性を与えますが、既存の顧客名を保持しません。While these operations make the database schema compatible, they don't preserve the existing customer names. 改善するには、次のように書き直します。To make it better, rewrite it as follows.

migrationBuilder.AddColumn<string>(
    name: "Name",
    table: "Customer",
    nullable: true);

migrationBuilder.Sql(
@"
    UPDATE Customer
    SET Name = FirstName + ' ' + LastName;
");

migrationBuilder.DropColumn(
    name: "FirstName",
    table: "Customer");

migrationBuilder.DropColumn(
    name: "LastName",
    table: "Customer");

ヒント

移行のスキャフォールディング手順では、(列の削除など) データが失われる場合に、警告が出ます。The migration scaffolding process warns when an operation might result in data loss (like dropping a column). その警告が表示されたら、移行コードが正しいことを特に確認してください。If you see that warning, be especially sure to review the migrations code for accuracy.

適切なコマンドを利用し、データベースに移行を適用します。Apply the migration to the database using the appropriate command.

Update-Database
dotnet ef database update

空の移行Empty migrations

モデル変更を行わずに移行を追加すると便利な場合があります。Sometimes it's useful to add a migration without making any model changes. この場合、新しい移行を追加すると、空のクラスのコード ファイルが作成されます。In this case, adding a new migration creates code files with empty classes. EF Core モデルに直接関連しない操作を実行するようにこの移行をカスタマイズできます。You can customize this migration to perform operations that don't directly relate to the EF Core model. この方法で管理すると便利なものは次のとおりです。Some things you might want to manage this way are:

  • フルテキスト検索Full-Text Search
  • 関数Functions
  • ストアド プロシージャStored procedures
  • トリガーTriggers
  • ViewsViews

移行を削除するRemove a migration

移行の追加後、適用する前に EF Core モデルの追加変更が必要なことに気付く場合があります。Sometimes you add a migration and realize you need to make additional changes to your EF Core model before applying it. 最後の移行を削除するには、このコマンドを使用します。To remove the last migration, use this command.

Remove-Migration
dotnet ef migrations remove

移行の削除後、追加のモデル変更を行い、もう一度追加できます。After removing the migration, you can make the additional model changes and add it again.

移行を元に戻すRevert a migration

移行をデータベースに既に適用しているが、元に戻す必要がある場合、同じコマンドを使用して移行を適用できますが、ロールバックする移行の名前を指定します。If you already applied a migration (or several migrations) to the database but need to revert it, you can use the same command to apply migrations, but specify the name of the migration you want to roll back to.

Update-Database LastGoodMigration
dotnet ef database update LastGoodMigration

SQL スクリプトを生成するGenerate SQL scripts

移行をデバッグするか、それを実稼働データベースに展開するとき、SQL スクリプトを生成すると便利です。When debugging your migrations or deploying them to a production database, it's useful to generate a SQL script. このスクリプトはさらに見直して正しいかどうかを確認し、実稼働データベースのニーズに合わせて調整できます。The script can then be further reviewed for accuracy and tuned to fit the needs of a production database. このスクリプトは、展開テクノロジとの連動でも利用できます。The script can also be used in conjunction with a deployment technology. 基本コマンドは次のとおりです。The basic command is as follows.

Script-Migration
dotnet ef migrations script

このコマンドにはいくつかのオプションがあります。There are several options to this command.

from 移行は、スクリプトの実行前にデータベースに適用される最後の移行にする必要があります。The from migration should be the last migration applied to the database before running the script. 移行が適用されていない場合、0 を指定します (これは既定です)。If no migrations have been applied, specify 0 (this is the default).

to 移行は、スクリプトの実行後にデータベースに適用される最後の移行です。The to migration is the last migration that will be applied to the database after running the script. これは既定でプロジェクトの最後の移行になります。This defaults to the last migration in your project.

idempotent スクリプトをオプションで生成できます。An idempotent script can optionally be generated. このスクリプトは、データベースにまだ適用されていない移行のみを適用します。This script only applies migrations if they haven't already been applied to the database. これは、データベースに適用された最後の移行が正確にわからない場合、あるいは複数のデータベースに展開するとき、いずれも移行が異なる可能性がある場合に便利です。This is useful if you don't exactly know what the last migration applied to the database was or if you are deploying to multiple databases that may each be at a different migration.

実行時に移行を適用するApply migrations at runtime

起動中または最初の実行中、実行時に移行を適用するアプリがあります。Some apps may want to apply migrations at runtime during startup or first run. Migrate() メソッドを使用してこれを行います。Do this using the Migrate() method.

このメソッドは、より高度なシナリオで利用される IMigrator サービスの上でビルドされます。This method builds on top of the IMigrator service, which can be used for more advanced scenarios. アクセスするには myDbContext.GetInfrastructure().GetService<IMigrator>() を利用します。Use myDbContext.GetInfrastructure().GetService<IMigrator>() to access it.

myDbContext.Database.Migrate();

警告

  • この方法は万人向けではありません。This approach isn't for everyone. ローカル データベースを利用するアプリには最適ですが、ほとんどのアプリケーションでは、SQL スクリプトの生成など、より堅牢な展開戦略が必要になります。While it's great for apps with a local database, most applications will require more robust deployment strategy like generating SQL scripts.
  • Migrate() の前に EnsureCreated() を呼び出さないでください。Don't call EnsureCreated() before Migrate(). EnsureCreated() は移行をバイパスしてスキーマを作成し、Migrate() が失敗します。EnsureCreated() bypasses Migrations to create the schema, which causes Migrate() to fail.

次の手順Next steps

詳細については、Entity Framework Core ツールのリファレンス - EF Core を参照してください。For more information, see Entity Framework Core ツールのリファレンス - EF Core.