移行の概要Migrations Overview

実プロジェクトでは、機能が実装されると、データ モデルが変更されます。新しいエンティティまたはプロパティが追加および削除されると、アプリケーションと一致させるために、データベース スキーマを変更しなければならなくなります。In real world projects, data models change as features get implemented: new entities or properties are added and removed, and database schemas needs to be changed accordingly to be kept in sync with the application. 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.

移行は、大まかに次のように機能します。At a high level, migrations function in the following way:

  • データ モデルの変更が採用されると、データベース スキーマを一致させておくために、必要な更新が記述された対応する移行を、開発者は EF Core ツールを使用して追加します。EF Core は、現在のモデルを古いモデルのスナップショットと比較して相違点を特定し、移行ソース ファイルを生成します。このファイルは、他のソース ファイルと同様に、ご自分のプロジェクトのソース管理で追跡できます。When a data model change is introduced, the developer uses EF Core tools to add a corresponding migration describing the updates necessary to keep the database schema in sync. EF Core compares the current model against a snapshot of the old model to determine the differences, and generates migration source files; the files can be tracked in your project's source control like any other source file.
  • 新しい移行が生成されると、それをさまざまな方法でデータベースに適用できます。Once a new migration has been generated, it can be applied to a database in various ways. EF Core では、適用されたすべての移行を特別な履歴テーブルに記録します。これにより、どの移行が適用されたか、またはされていないかを知ることができます。EF Core records all applied migrations in a special history table, allowing it to know which migrations have been applied and which haven't.

このページの残りの部分では、移行手順を初心者向けに詳細に説明します。The rest of this page is a step-by-step beginner's guide for using migrations. さらなる詳細については、このセクションの他のページを参照してください。Consult the other pages in this section for more in-depth information.

作業の開始Getting started

次の単純なモデルが含まれる、あなたの初めての EF Core アプリケーションが完成したとします。Let's assume you've just completed your first EF Core application, which contains the following simple model:

public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
}

開発時に、Create API と Drop API を使用して、すばやく反復処理を行い、ご自分のモデルに必要に応じた変更を加えたとします。しかし、今度ご自分のアプリケーションが運用環境に移行することになったので、データベース全体を削除せず、スキーマを安全に発展させる方法が必要です。During development, you may have used the Create and Drop APIs to iterate quickly, changing your model as needed; but now that your application is going to production, you need a way to safely evolve the schema without dropping the entire database.

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

まず、EF Core のコマンドライン ツールをインストールする必要があります。First, you'll have to install the EF Core command-line tools:

ご自分の最初の移行を作成するCreate your first migration

これで、ご自分の最初の移行を追加する準備ができました。You're now ready to add your first migration! EF Core に InitialCreate という名前の移行を作成するように指示します。Instruct EF Core to create a migration named InitialCreate:

dotnet ef migrations add InitialCreate

EF Core により、ご自分のプロジェクトに Migrations というディレクトリが作成され、いくつかのファイルが生成されます。EF Core will create a directory called Migrations in your project, and generate some files. EF Core で生成された内容を確認し、場合によっては修正することが推奨されますが、ここではそれは省きます。It's a good idea to inspect what exactly EF Core generated - and possibly amend it - but we'll skip over that for now.

ご自分のデータベースとスキーマを作成するCreate your database and schema

この時点で、EF にご自分のデータベースを作成させ、移行からご自分のスキーマを作成できます。At this point you can have EF create your database and create your schema from the migration. これは、次のように行います。This can be done via the following:

dotnet ef database update

これで完了です。SQL を 1 行も記述せずに、ご自分のアプリケーションをご自分の新しいデータベースで実行する準備ができました。That's all there is to it - your application is ready to run on your new database, and you didn't need to write a single line of SQL. この方法での移行の適用は、ローカルでの開発には適していますが、運用環境には適していません。詳細については、移行の適用に関するページを参照してください。Note that this way of applying migrations is ideal for local development, but is less suitable for production environments - see the Applying Migrations page for more info.

ご自分のモデルを発展させるEvolving your model

数日後、ご自分のブログに作成のタイムスタンプを追加するように求められました。A few days have passed, and you're asked to add a creation timestamp to your blogs. ご自分のアプリケーションに必要な変更を行ったので、現在、ご自分のモデルは次のようになっています。You've done the necessary changes to your application, and your model now looks like this:

public class Blog
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime CreatedTimestamp { get; set; }
}

現在、ご自分のモデルとご自分の実稼働データベースは一致しなくなっています。ご自分のデータベース スキーマに新しい列を追加する必要があります。Your model and your production database are now out of sync - we must add a new column to your database schema. このために、新しい移行を作成します。Let's create a new migration for this:

dotnet ef migrations add AddBlogCreatedTimestamp

移行には、後でプロジェクト履歴がわかりやすいように、わかりやすい名前が付いていることに着目してください。Note that we give migrations a descriptive name, to make it easier to understand the project history later.

これはプロジェクトの最初の移行ではないため、EF Core では、列の追加前に、ご自分の更新されたモデルを古いモデルのスナップショットと比較します。このモデルのスナップショットとは、移行を追加したときに EF Core によって生成されるファイルの 1 つであり、ソース管理にチェックインされます。Since this isn't the project's first migration, EF Core now compares your updated model against a snapshot of the old model, before the column was added; the model snapshot is one of the files generated by EF Core when you add a migration, and is checked into source control. その比較に基づき、EF Core は列が追加されたことを検出し、適切な移行を追加します。Based on that comparison, EF Core detects that a column has been added, and adds the appropriate migration.

これで、以前と同じようにご自分の移行を適用できるようになりました。You can now apply your migration as before:

dotnet ef database update

今回は、データベースが既に存在していることが EF によって検出されていることに着目してください。Note that this time, EF detects that the database already exists. また、上記の最初の移行が適用されたとき、その事実がご自分のデータベースの特別な移行履歴テーブルに記録されました。これにより、EF は新しい移行のみを自動的に適用します。In addition, when our first migration was applied above, this fact was recorded in a special migrations history table in your database; this allows EF to automatically apply only the new migration.

モデルの一部を除外するExcluding parts of your model

注意

この機能は EF Core 5.0 で導入されました。This feature was introduced EF in Core 5.0.

別の DbContext の型を参照する必要がある場合があります。Sometimes you may want to reference types from another DbContext. これにより、移行の競合が発生する可能性があります。This can lead to migration conflicts. これを回避するには、いずれかの DbContext の移行から型を除外します。To prevent this, exclude the type from the migrations of one of the DbContexts.

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<IdentityUser>()
        .ToTable("AspNetUsers", t => t.ExcludeFromMigrations());
}

次の手順Next steps

上では、移行について簡単に説明しました。The above was only a brief introduction to migrations. 移行の管理およびそれの適用などについては、その他のドキュメント ページを参照してください。Please consult the other documentation pages to learn more about managing migrations, applying them, and other aspects. .NET Core CLI ツール リファレンスにも、さまざまなコマンドに関する有用な情報があります。The .NET Core CLI tool reference also contains useful information on the different commands

その他のリソースAdditional resources