Database Migrations in ASP.NET Core Zero

In the previous article, we introduced how to interact with databases using Entity Framework Core. In this article, we’ll explore the concept of database migrations and how to use Entity Framework Core for versioning and migrating your database schema. This process is essential for ensuring consistency between your database structure and application data models.

What Is a Database Migration?

A database migration is a form of version control for your database schema. It enables developers to synchronize database changes when modifying their data models. With migrations, you can easily add, modify, or delete tables, columns, and constraints—without manually writing SQL scripts.

Why Use Database Migrations?

• Version Control: Migration files are part of your source code and can be tracked in version control systems, allowing you to record and audit every database change.
• Simplified Updates: Migrations let you apply new schema changes to existing databases in a single, reliable step.
• Team Collaboration: In team-based development, shared migration files ensure all developers can pull the latest schema changes and keep their local databases aligned with the main database.

Creating a Database Migration

Before proceeding, ensure that Entity Framework Core is installed and that you’ve defined at least one data model. We’ll now walk through two key steps:

1. Creating a migration
2. Applying the migration

Suppose, as in the previous article, you’ve defined a simple Product model like this:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

1. Creating a Migration

Make sure you’re in your project’s root directory in the terminal, then run the following command to generate an initial migration:

dotnet ef migrations add InitialCreate

This command generates a migration file containing code that maps the Product class to a corresponding database table. The file appears in the project’s Migrations folder and follows the naming convention Timestamp_MigrationName.

2. Applying the Migration

After creating the migration, apply it to the database to create the corresponding table:

dotnet ef database update

This command updates the database to the latest migration state. Entity Framework Core applies all pending migrations—in this case, creating the Products table.

Migration Example

Here’s an example of an auto-generated migration file:

public partial class InitialCreate : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.CreateTable(
            name: "Products",
            columns: table => new
            {
                Id = table.Column<int>(nullable: false)
                    .Annotation("SqlServer:Identity", "1, 1"),
                Name = table.Column<string>(nullable: true),
                Price = table.Column<decimal>(nullable: false)
            },
            constraints: table =>
            {
                table.PrimaryKey("PK_Products", x => x.Id);
            });
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropTable(
            name: "Products");
    }
}

In this code, the Up method defines the operations to perform when applying the migration, while the Down method defines how to reverse (roll back) those changes.

Modifying Migrations

When your data model evolves—for example, adding a new Category property to the Product class—you first update the model:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public string Category { get; set; }  // New field
}

Then generate a new migration:

dotnet ef migrations add AddCategoryToProduct

Finally, apply it:

dotnet ef database update

This adds the Category column to the Products table.

Best Practices for Migrations

1. Frequent, Small Migrations: Prefer many small, focused migrations over large, infrequent ones—this reduces merge conflicts and simplifies debugging.
2. Code Review: Always review migration files before merging them into shared branches to catch potential design issues or unintended side effects.
3. Data Migration Logic: When introducing new fields or restructuring data, include custom SQL or C# logic within the migration to populate or transform existing data—ensuring data integrity and consistency.

Summary

In this article, we covered the fundamentals of database migrations in Entity Framework Core, including how to create and apply them. By leveraging migrations, you maintain alignment between your application models and database schema—making database management more predictable, collaborative, and maintainable. In upcoming articles, we’ll dive into performing CRUD operations in the database—a core aspect of application development.