Migration in Entity Framework Core

Migration is a way to keep the database schema in sync with the EF Core model by preserving data.

EF Core Migration

As per the above figure, EF Core API builds the EF Core model from the domain (entity) classes and EF Core migrations will create or update the database schema based on the EF Core model. Whenever you change the domain classes, you need to run migration to keep the database schema up to date.

EF Core migrations are a set of commands which you can execute in NuGet Package Manager Console or in dotnet Command Line Interface (CLI).

The following table lists important migration commands in EF Core.

PMC Command dotnet CLI command Usage
add-migration <migration name> Add <migration name> Creates a migration by adding a migration snapshot.
Remove-migration Remove Removes the last migration snapshot.
Update-database Update Updates the database schema based on the last migration snapshot.
Script-migration Script Generates a SQL script using all the migration snapshots.

Adding a Migration

At the very first time, you defined the initial domain classes. At this point, there is no database for your application which can store the data from your domain classes. So, firstly, you need to create a migration.

Open the Package Manager Console from the menu Tools -> NuGet Package Manager -> Package Manager Console in Visual Studio and execute the following command to add a migration.

Package Manager Console
PM> add-migration MyFirstMigration

If you are using dotnet Command Line Interface, execute the following command.

> dotnet ef migrations add MyFirstMigration

In the above commands, MyFirstMigration is the name of a migration. This will create three files in the Migrations folder of your project, as shown below.

  1. <timestamp>_<Migration Name>.cs: The main migration file which includes migration operations in the Up() and Down() methods. The Up() method includes the code for creating DB objects and Down() method includes code for removing DB objects.
  2. <timestamp>_<Migration Name>.Designer.cs: The migrations metadata file which contains information used by EF Core.
  3. <contextclassname>ModelSnapshot.cs: A snapshot of your current model. This is used to determine what changed when creating the next migration.

Now, after creating a migration snapshot, it's time to create the database.

Creating or Updating the Database

Use the following command to create or update the database schema.

Package Manager Console
PM> Update-Database
> dotnet ef database update

The Update command will create the database based on the context and domain classes and the migration snapshot, which is created using the add-migration or add command.

If this is the first migration, then it will also create a table called __EFMigrationsHistory, which will store the name of all migrations, as and when they will be applied to the database.

Removing a Migration

You can remove the last migration if it is not applied to the database. Use the following remove commands to remove the last created migration files and revert the model snapshot.

Package Manager Console
PM> remove-migration
> dotnet ef migrations remove

The above commands will remove the last migration and revert the model snapshot to the previous migration. Please note that if a migration is already applied to the database, then it will throw the following exception.

The migration <migration name> has already been applied to the database. Revert it and try again. If the migration has been applied to other databases, consider reverting its changes using a new migration.

Reverting a Migration

Suppose you changed your domain class and created the second migration named MySecondMigration using the add-migration command and applied this migration to the database using the Update command. But, for some reason, you want to revert the database to the previous state. In this case, use the update-database <migration name> command to revert the database to the specified previous migration snapshot.

Package Manager Console
PM> Update-database MyFirstMigration
> dotnet ef database update MyFirstMigration.

The above command will revert the database based on a migration named MyFirstMigration and remove all the changes applied for the second migration named MySecondMigration. This will also remove MySecondMigration entry from the __EFMigrationsHistory table in the database.

Note: This will not remove the migration files related to MySecondMigration. Use the remove commands to remove them from the project.

Generating a SQL Script

Use the following command to generate a SQL script for the database.

Package Manager Console
PM> script-migration
> dotnet ef migrations script

The above script command will include a script for all the migrations by default. You can specify a range of migrations by using the -to and -from options.