移行の適用

移行を追加したら、それらを展開し、データベースに適用する必要があります。 これを行うためのさまざまな戦略があります。一部は運用環境に適しており、その他のものは開発ライフサイクルに適しています。

デプロイ戦略を選択する

自動デプロイの場合は、 移行バンドルを使用します。 バンドルは、CI で生成され、.NET SDK、EF Core ツール、またはアプリケーションのソース コードなしで後で実行できるデプロイ成果物です。 SQL を適用する前に、SQL を確認、変更、アーカイブ、または DBA に渡す必要がある場合は、代わりに SQL スクリプト を使用します。

ローカル開発では、通常、 dotnet ef database update または Update-Database が最も簡単なオプションです。 熱望プロジェクトでは、 Ef Core 移行の統合 を使用して、ローカル移行の実行を調整し、バンドルまたはスクリプトを発行する必要があります。

EF Core 9 以降では、移行ロックが使用されます。 同期操作とツール呼び出し UseSeeding。非同期操作は UseAsyncSeedingを呼び出します。

スキーマを変更するアクセス許可を持つデプロイには、別の ID を使用します。 アプリケーションが実行時に使用する ID には、通常、アプリケーションがデータの読み取りと書き込みに必要なアクセス許可のみを持つ必要があります。

SQL スクリプト

SQL スクリプトは、デプロイ プロセスで、生成された SQL を実行前に検査または変更する必要がある場合に推奨されます。 この戦略の利点は次のとおりです。

• SQL スクリプトの正確性を審査することができます。スキーマ変更を運用データベースに適用することは、データ損失を伴う可能性のある危険な操作であるため、このことは重要です。
• 場合によっては、運用データベースの特定のニーズに合わせてスクリプトを調整できます。
• SQL スクリプトは展開テクノロジと組み合わせて使用でき、CI プロセスの一部として生成することもできます。
• SQL スクリプトは DBA に提供でき、個別に管理およびアーカイブすることもできます。

dotnet ef migrations script

dotnet ef migrations script --idempotent --output artifacts/migrations.sql

dotnet ef migrations script AddNewTables

dotnet ef migrations script AddNewTables AddAuditTable

Script-Migration

Script-Migration -Idempotent -Output artifacts\migrations.sql

Script-Migration AddNewTables

Script-Migration AddNewTables AddAuditTable

スクリプト生成では、生成する必要がある移行の範囲を示す次の 2 つの引数を受け取ります。

• from 移行は、スクリプトの実行前にデータベースに適用される最後の移行にする必要があります。 移行が適用されていない場合、0 を指定します (これは既定です)。
• to 移行は、スクリプトの実行後にデータベースに適用される最後の移行です。 これは既定でプロジェクトの最後の移行になります。

移行スクリプトは、既存のデータベースを更新します。 スクリプトを適用する前に、インフラストラクチャのデプロイまたはデータベース管理プロセスを通じてデータベース自体をプロビジョニングします。 通常、データベースの作成には、別の接続、昇格されたアクセス許可、およびプロバイダー固有の構成が必要です。

べき等 SQL スクリプト

上記で生成される SQL スクリプトは、スキーマをある移行から別の移行に変更するためにのみ適用できます。スクリプトを適切に適用し、正しい移行状態のデータベースに対してのみ適用することは、ユーザーの責任です。 EF Core では、べき等スクリプトの生成もサポートしています。これは、既に適用されている移行を (移行履歴テーブルを使用して) 内部的に検査し、不足している移行のみを適用するものです。 これは、データベースに適用された最後の移行が正確にわからない場合、あるいは移行が異なる可能性がある複数のデータベースに展開する場合に便利です。

べき等スクリプトのサポートは、データベース プロバイダーによって異なります。 たとえば、SQLite では現在、べき等移行スクリプトの生成はサポートされていません。

次の例では、べき等移行が生成されます。

dotnet ef migrations script --idempotent

Script-Migration -Idempotent

コマンド ライン ツール

EF コマンド ライン ツールを使用して、データベースに移行を適用できます。 このアプローチは移行のローカル開発とテストでは生産性が高いですが、運用データベースの管理には最適ではありません。

• SQL コマンドがツールによって直接適用され、開発者に検査や変更を行う機会がありません。 これは運用環境では危険な場合があります。
• .NET SDK と EF ツールは運用サーバーにインストールする必要があり、プロジェクトのソース コードが必要です。

dotnet ef database update

dotnet ef database update AddNewTables

Update-Database

Update-Database AddNewTables

コマンド ライン ツールを使用して移行を適用する方法の詳細については、「EF Core ツールのリファレンス」を参照してください。

環境と構成

ツールは、アプリケーション コードを実行して DbContextを構築します。 そのため、プロバイダーの選択、接続文字列、およびモデルの構成は、アプリケーション環境によって異なります。 EF Core のデザイン時ツールでは、ASPNETCORE_ENVIRONMENTもDOTNET_ENVIRONMENTも設定されていない場合、Development環境が使用されます。

デプロイ成果物を生成するとき、およびバンドルを実行するときに、環境を明示的に設定します。 たとえば、PowerShell で以下を実行します。

$env:ASPNETCORE_ENVIRONMENT = 'Production'
dotnet ef migrations bundle --output artifacts\efbundle.exe

$env:ASPNETCORE_ENVIRONMENT = 'Production'
.\efbundle.exe --connection $env:DEPLOYMENT_CONNECTION_STRING

または POSIX と互換性のあるシェルの場合:

ASPNETCORE_ENVIRONMENT=Production \
    dotnet ef migrations bundle --output artifacts/efbundle

ASPNETCORE_ENVIRONMENT=Production \
    ./efbundle --connection "$DEPLOYMENT_CONNECTION_STRING"

これにより、バンドルが開発ユーザー シークレットを予期せず読み込めなくなります。 バンドルのより安全な既定の環境は 、dotnet/efcore#36188 によって追跡されます。 Visual Studio発行エクスペリエンスでの環境の選択は、dotnet/efcore#11950 によって追跡されます。

運用環境の接続文字列をソース管理に格納したり、バンドルに埋め込んだりしないでください。 デプロイ システムのシークレット ストアからデプロイ接続を指定します。 デプロイ ID にはスキーマのアクセス許可が必要です。通常、通常のアプリケーション ID では使用しないでください。

Bundles

移行バンドルは、データベースに移行を適用するために使用できる単一ファイルの実行可能ファイルです。 これらは、次のような SQL スクリプトとコマンドライン ツールの欠点の一部に対処します。

• SQL スクリプトを実行するには、追加のツールが必要です。
• これらのツールによるトランザクション処理とエラー時の続行動作には一貫性がなく、予期できない場合もあります。 そのため、移行の適用時にエラーが発生した場合に、データベースが未定義の状態になる可能性があります。
• バンドルは、CI プロセスの一部として生成することができ、後で配置プロセスの一部として簡単に実行することができます。
• バンドルは、.NET SDK または EF ツール (自己完結型の場合は .NET ランタイム) をインストールせずに実行でき、プロジェクトのソース コードは必要ありません。
• バンドルでは、EF Core の移行ロックを使用し、構成された UseSeeding ロジックを実行します。

SQL スクリプトとは異なり、バンドルには現在、それが実行する SQL を検査したり、それに含まれる移行を一覧表示したりする方法はありません。 デプロイで SQL レビューが必要な場合は、代わりにスクリプトを生成します。 バンドル検査の機能強化は、 dotnet/efcore#25872 によって追跡されます。

dotnet ef migrations bundle --output artifacts/efbundle

dotnet ef migrations bundle --self-contained --target-runtime linux-x64 --output artifacts/efbundle

Bundle-Migration -Output artifacts\efbundle.exe

Bundle-Migration -SelfContained -TargetRuntime linux-x64 -Output artifacts\efbundle

バンドルの作成の詳細については、「EF Core ツールのリファレンス」を参照してください。

efbundle

生成される実行可能ファイルは、既定では efbundle という名前になります。 これは、データベースを最新の移行に更新するために使用できます。 これは、dotnet ef database update または Update-Database を実行するのと同等です。

Arguments:

Options:

次の例では、指定したユーザー名と資格情報を使用して、ローカル SQL Server インスタンスに移行を適用します。

.\efbundle.exe --connection 'Data Source=(local)\MSSQLSERVER;Initial Catalog=Blogging;User ID=myUsername;Password={;'$Credential;'here'}'

データベースをロールバックするには、引き続き適用する必要がある移行を渡します。 0渡すと、すべての移行が元に戻ります。

.\efbundle.exe PreviousMigration --connection 'Data Source=(local)\MSSQLSERVER;Initial Catalog=Blogging;Integrated Security=True'
.\efbundle.exe 0 --connection 'Data Source=(local)\MSSQLSERVER;Initial Catalog=Blogging;Integrated Security=True'

コンテナーとデプロイ ジョブ

ビルド中にバンドルを生成し、データベースが正常になった後に 1 回限りのデプロイ ジョブとして実行します。 アプリケーション イメージに SDK をインストールしたり、 dotnet ef を実行したりしないでください。また、すべてのアプリケーション レプリカがそのエントリ ポイントから移行を実行するわけではありません。 正常に終了した後に移行コンテナーを再起動しないようにデプロイ プラットフォームを構成します。

アスパイア アプリケーションの場合、 AddEFMigrations はローカル開発時に移行を調整できます。 発行中、 PublishAsMigrationBundle はバンドルまたはコンテナー イメージを出力でき、 PublishAsMigrationScript は SQL スクリプトを出力できます。 Azure Container Apps、Docker Compose、Kubernetes のワンショット ジョブ構成については、アスパイアでの EF Core 移行の適用に関するページを参照してください。

移行バンドルのサンプルでは、2 つの SQLite 移行、べき等シード処理、フォワード アプリケーション、ロールバック セーフ シード処理を示します。

移行バンドルの例

バンドルには、組み込む移行が必要です。 これらは「dotnet ef migrations add」を使用して作成されるもので、Create your first migrationで説明されています。 移行を展開する準備ができたら、dotnet ef migrations bundle を使用してバンドルを作成します。 例えば次が挙げられます。

PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations bundle
Build started...
Build succeeded.
Building bundle...
Done. Migrations Bundle: C:\local\AllTogetherNow\SixOh\efbundle.exe
PS C:\local\AllTogetherNow\SixOh>

出力は、対象のオペレーティング システムに適した実行可能ファイルです。 私の場合、これはx64 Windowsなので、efbundle.exeローカルフォルダにドロップされます。 この実行可能ファイルを実行すると、その中に含まれる移行が適用されます。

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe
Applying migration '20210903083845_MyMigration'.
Done.
PS C:\local\AllTogetherNow\SixOh>

dotnet ef database update や Update-Database と同様に、移行は、まだ適用されていない場合にのみ、データベースに適用されます。 たとえば、同じバンドルを再度実行しても、適用する新しい移行がないため、何も行われません。

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe
No migrations were applied. The database is already up to date.
Done.
PS C:\local\AllTogetherNow\SixOh>

ただし、モデルを変更し、dotnet ef migrations add を使用してさらに移行を生成した場合は、適用できる状態の新しい実行可能ファイルにそれらをバンドルできます。 例えば次が挙げられます。

PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations add SecondMigration
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations add Number3
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'
PS C:\local\AllTogetherNow\SixOh> dotnet ef migrations bundle --force
Build started...
Build succeeded.
Building bundle...
Done. Migrations Bundle: C:\local\AllTogetherNow\SixOh\efbundle.exe
PS C:\local\AllTogetherNow\SixOh>

この新しいバンドルを実行すると、これら 2 つの新しい移行がデータベースに適用されます。

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe
Applying migration '20210903084526_SecondMigration'.
Applying migration '20210903084538_Number3'.
Done.
PS C:\local\AllTogetherNow\SixOh>

既定では、バンドルはアプリケーションの構成からデータベースの接続文字列を使用します。 ただし、コマンド ラインで接続文字列を渡すことで、別のデータベースを移行できます。 例えば次が挙げられます。

PS C:\local\AllTogetherNow\SixOh> .\efbundle.exe --connection "Data Source=(LocalDb)\MSSQLLocalDB;Database=SixOhProduction"
Applying migration '20210903083845_MyMigration'.
Applying migration '20210903084526_SecondMigration'.
Applying migration '20210903084538_Number3'.
Done.
PS C:\local\AllTogetherNow\SixOh>

実行時に移行を適用する

アプリケーション自体が、通常は起動時にプログラムによって移行を適用することができます。 EF Core 9 以降では、データベース全体のロックを使用して移行の実行が保護されるため、単純なデプロイを優先し、スタートアップ移行の動作を許容できるアプリケーションでこれを許容できます。 レビュー、最小特権の資格情報、調整されたロールアウト、または高可用性が重要な場合は、別の移行デプロイ手順が推奨されます。

次のトレードオフについて考えてみましょう。

• EF 9より前のバージョンでは、アプリケーションの複数のインスタンスが実行されている場合、両方のアプリケーションが同時に移行を適用しようとして失敗する可能性があります (最悪の場合、データが破損する可能性があります)。
• 同様に、アプリケーションが移行している間に別のアプリケーションがデータベースにアクセスした場合、重大な問題が発生する可能性があります。
• アプリケーションに、データベース スキーマを変更するための昇格されたアクセス権が必要です。 一般に、アプリケーションのデータベース アクセス許可を運用環境で制限することが推奨されています。
• 問題が発生した場合、適用された移行をロールバックできる必要があります。 他の戦略では、これを簡単かつすぐに実行できます。
• SQL コマンドがプログラムによって直接適用され、開発者に検査や変更を行う機会がありません。 これは運用環境では危険な場合があります。

移行をプログラムで適用するには、context.Database.MigrateAsync() を呼び出します。 たとえば、一般的な ASP.NET アプリケーションでは、次の操作を実行できます。

public static async Task Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    using (var scope = host.Services.CreateScope())
    {
        var db = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
        await db.Database.MigrateAsync();
    }

    host.Run();
}

MigrateAsync() は、より高度なシナリオで利用される IMigrator サービスの上にビルドされます。 アクセスするには myDbContext.GetInfrastructure().GetService<IMigrator>() を利用します。

移行時のロック

EF Core 9以降では、MigrateAsyncおよびMigrateが自動的にデータベース全体のロックを取得してから移行を適用します。 これにより、複数のアプリケーション インスタンスが同時に移行を実行することによって発生する可能性があるデータベースの破損から保護されます。これは、 実行時に移行を適用する場合の一般的なシナリオです。 ロックは、 シード処理コードを含め、移行の実行期間中保持され、操作が完了すると自動的に解放されます。

移行ロックは、次のいずれかの方法を使用して移行が適用されるときに適用されます。

• dotnet ef database update(.NET CLI)
• Update-Database (パッケージ マネージャー コンソール)
• 移行バンドル
• MigrateAsync および Migrate (ランタイム移行)

SQL スクリプト は EF Core の外部で適用されるため、移行ロックの影響を受けません。

制限事項

• 明示的トランザクションでMigrateAsyncをラッピングすることはサポートされていません。 詳細については、「明示的なトランザクションで移行を適用すると例外がスローされます」を参照してください。
• SQLite では、破棄された移行ロックによって 後続の移行がブロックされる可能性があります。