-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
433 additions
and
203 deletions.
There are no files selected for viewing
164 changes: 164 additions & 0 deletions
164
entity-framework/core/managing-schemas/migrations/applying.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,164 @@ | ||
--- | ||
title: Applying Migrations - EF Core | ||
author: bricelam | ||
ms.author: bricelam | ||
ms.date: 05/06/2020 | ||
uid: core/managing-schemas/migrations/applying | ||
--- | ||
# Applying Migrations | ||
|
||
Once your migrations have been added, they need to be deployed and applied to your databases. There are various strategies for doing this, with some being more appropriate for production environments, and others for the development lifecycle. | ||
|
||
## SQL scripts | ||
|
||
The recommended way to deploy migrations to a production database is by generating SQL scripts. The advantages of this strategy include the following: | ||
|
||
* SQL scripts can be reviewed for accuracy; this is important since applying schema changes to production databases is a potentially dangerous operation that could involve data loss. | ||
* In some cases, the scripts can be tuned to fit the specific needs of a production database. | ||
* SQL scripts can be used in conjunction with a deployment technology. | ||
* SQL scripts can be provided to a DBA, and can be managed and archived separately. | ||
|
||
### [.NET Core CLI](#tab/dotnet-core-cli) | ||
|
||
#### Basic Usage | ||
|
||
The following generates a SQL script from a blank database to the latest migration: | ||
|
||
```dotnetcli | ||
dotnet ef migrations script | ||
``` | ||
|
||
#### With From (to implied) | ||
|
||
The following generates a SQL script from the given migration to the latest migration. | ||
|
||
```dotnetcli | ||
dotnet ef migrations script AddNewTables | ||
``` | ||
|
||
#### With From and To | ||
|
||
The following generates a SQL script from the `from` migration to the specified `to` migration. | ||
|
||
```dotnetcli | ||
dotnet ef migrations script AddNewTables AddAuditTable | ||
``` | ||
|
||
You can use a `from` that is newer than the `to` in order to generate a rollback script. *Please take note of potential data loss scenarios.* | ||
|
||
### [Visual Studio](#tab/vs) | ||
|
||
The following generates a SQL script from a blank database to the latest migration: | ||
|
||
#### Basic Usage | ||
|
||
``` powershell | ||
Script-Migration | ||
``` | ||
|
||
#### With From (to implied) | ||
|
||
The following generates a SQL script from this migration to the latest migration. | ||
|
||
```powershell | ||
Script-Migration AddNewTables | ||
``` | ||
|
||
#### With From and To | ||
|
||
The following generates a SQL script from the `from` migration to the specified `to` migration. | ||
|
||
```powershell | ||
Script-Migration AddNewTables AddAuditTable | ||
``` | ||
You can use a `from` that is newer than the `to` in order to generate a rollback script. *Please take note of potential data loss scenarios.* | ||
|
||
*** | ||
|
||
There are several options to this command. | ||
|
||
The **from** migration should be the last migration applied to the database before running the script. If no migrations have been applied, specify `0` (this is the default). | ||
|
||
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 SQL scripts | ||
|
||
The SQL scripts generated above can only be applied to change your schema from one migration to another; it is your responsibility to apply the script appropriately, and only to database in the correct migration state. EF Core also supports generating **idempotent** scripts, which internally check which migrations have already been applied, and only apply missing ones. 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. | ||
|
||
The following generates idempotent migrations: | ||
|
||
#### [.NET Core CLI](#tab/dotnet-core-cli) | ||
|
||
```dotnetcli | ||
dotnet ef migrations add AddNewTables --idempotent | ||
``` | ||
|
||
#### [Visual Studio](#tab/vs) | ||
|
||
``` powershell | ||
Add-Migration AddNewTables -Idempotent | ||
``` | ||
|
||
> [!WARNING] | ||
> Idempotent scripts have some known limitations and will not work in all scenarios. | ||
*** | ||
|
||
## Command-line tools | ||
|
||
The EF command-line tools can be used to apply migrations to a database. While productive for local development and testing of migrations, this approach is inappropriate for management of production databases: | ||
|
||
* The SQL commands are applied directly by the tool, without giving the developer a change to inspect or modify them. This can be dangerous in a production environment. | ||
* The .NET SDK and the EF tool must be installed on production servers. | ||
|
||
### [.NET Core CLI](#tab/dotnet-core-cli) | ||
|
||
The following updates your database to the latest migration: | ||
|
||
```dotnetcli | ||
dotnet ef database update | ||
``` | ||
|
||
The following updates your database to a given migration: | ||
|
||
```dotnetcli | ||
dotnet ef database update AddNewTables | ||
``` | ||
|
||
### [Visual Studio](#tab/vs) | ||
|
||
The following updates your database to the latest migration: | ||
|
||
``` powershell | ||
Update-Database | ||
``` | ||
|
||
The following updates your database to a given migration: | ||
|
||
``` powershell | ||
Update-Database AddNewTables | ||
``` | ||
|
||
*** | ||
|
||
Note that this can be used to roll back to an earlier migration as well. *Please take note of potential data loss scenarios.* | ||
|
||
For more information on applying migrations via the command-line tools, see the [EF Core tools reference](xref:core/miscellaneous/cli/index). | ||
|
||
## Apply migrations at runtime | ||
|
||
It's possible for the application itself to apply migrations programmatically, typically during startup. While productive for local development and testing of migrations, this approach is inappropriate for management of production databases: | ||
|
||
* If multiple instances of your application are running, both applications could attempt to apply the migration concurrently and fail. | ||
* The SQL commands are applied directly by the program, without giving the developer a change to inspect or modify them. This can be dangerous in a production environment. | ||
|
||
``` csharp | ||
myDbContext.Database.Migrate(); | ||
``` | ||
|
||
This method builds on top of the `IMigrator` service, which can be used for more advanced scenarios. Use `myDbContext.GetInfrastructure().GetService<IMigrator>()` to access it. | ||
|
||
> [!WARNING] | ||
> | ||
> * Carefully consider before using this approach in production. Experience has shown that the simplicity of this deployment strategy is outweighed by the problem it brings. Consider using SQL scripts instead. | ||
> * Don't call `EnsureCreated()` before `Migrate()`. `EnsureCreated()` bypasses Migrations to create the schema, which causes `Migrate()` to fail. |
Oops, something went wrong.