Introduction to Entity Framework Core Migrations

Database schema changes are an inevitable part of application development. Entity Framework Core (EF Core) Migrations provide a powerful and flexible way to manage these changes incrementally. Migrations allow you to evolve your database schema alongside your application code, ensuring that your data model and your database remain synchronized.

Key Benefits of Migrations:

  • Version Control for your Schema: Treat your database schema like code, with history and rollback capabilities.
  • Cross-Platform: Works consistently across different operating systems and databases.
  • Automation: Integrate migrations into your build and deployment pipelines.
  • Code-First Approach: Define your data model in C# or F#, and let Migrations generate the SQL to create or alter your database.

Getting Started with Migrations

To use Migrations, you first need to install the necessary NuGet packages:

dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.Tools

Once installed, you can enable Migrations for your DbContext using the Package Manager Console or the .NET CLI:

Using .NET CLI:

dotnet ef migrations add InitialCreate

This command generates your first migration. The name InitialCreate is arbitrary; choose a descriptive name for your migration.

Understanding Migration Files

After running the add command, EF Core creates a Migrations folder in your project. Inside this folder, you'll find:

  • A timestamped folder for each migration (e.g., 20231027100000_InitialCreate).
  • Inside the timestamped folder, you'll find two files:
    • <MigrationName>.cs: Contains the C# code to apply and reverse the migration (e.g., creating tables, adding columns).
    • <MigrationName>.Designer.cs: Contains metadata about the migration.

Applying Migrations

To apply your pending migrations to the database, use the database update command:

Using .NET CLI:

dotnet ef database update

This command will execute the SQL commands generated by the migrations against your target database. If you have multiple migrations, it will apply them in order.

Common Migration Operations

Creating a Migration

When you make changes to your entity models or DbContext, you need to generate a new migration to reflect these changes in the database.

dotnet ef migrations add AddEmailToUser

Generating SQL Scripts

You can generate SQL scripts for your migrations without applying them directly:

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

Reverting Migrations

If you need to undo a migration, you can use the database update command with a specific migration name:

dotnet ef database update <PreviousMigrationName>

Or, to revert to the previous state:

dotnet ef database update 0

Resetting the Database

You can reset your database to an empty state and reapply all migrations:

dotnet ef database drop
dotnet ef migrations add InitialCreate
dotnet ef database update

Note: Dropping and recreating a database will result in data loss. Use this command with caution, especially in production environments.

Advanced Scenarios

  • Custom SQL: Execute raw SQL commands within your migrations.
  • Data Seeding: Populate your database with initial data.
  • History Table: EF Core uses a table (__EFMigrationsHistory by default) to track which migrations have been applied.