Your First EF Core Migration: Step-by-Step with Real Examples

I still remember the first time I ran my EF Core migration in one of my projects, it was for a payment system where we needed to store EMV transaction logs. I thought, “This will probably take the whole day, and maybe break something”.

Surprisingly, it didn’t break anything, at least not on the first try. But I learned a lot about how EF Core migrations work, and I want to share with you the same step-by-step process I used so you can do your first migration without fear.

Think of this as me sitting beside you, walking you through my laptop, and saying “Okay, let’s run this command, oh wait, double-check your connection string first.”

What is EF Core Migration Anyway?

Let’s make it simple. An EF Core migration is basically a way for EF Core to take your C# model classes and automatically create or update your database schema based on them.

It’s like having a smart assistant that says:

“Hey, I noticed you added a new column in your class. Do you want me to update the table in the database for you?”

In one of my EMV payment projects, we had to add a MerchantName column to the Payment table. Instead of writing the ALTER TABLE SQL manually, I just let EF Core handle it, and it saved me hours.

Before You Start – Prerequisites

Before you run your first migration, you need to make sure:

You have .NET 9 SDK installed (you can use dotnet –version to check).
EF Core package is installed.
You have your database connection string ready.
You have at least one DbContext and one model class.

Step 1 – Install EF Core Tools

Open your terminal and run:

Bash

dotnet tool install --global dotnet-ef

dotnet tool install --global dotnet-ef

Why global? Because you can use it in any project without installing again. In my case, I often jump between different projects, some for HR systems, some for payments and having it global is just less hassle.

Step 2 – Prepare Your DbContext and Models

Here’s a simple example inspired by my payment project:

public class Payment
{
    public int Id { get; set; }
    public string CardNumberMasked { get; set; }
    public decimal Amount { get; set; }
    public DateTime TransactionDate { get; set; }
}

public class AppDbContext : DbContext
{
    public DbSet<Payment> Payments { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlServer("Your_Connection_String_Here");
    }
}

public class Payment
{
    public int Id { get; set; }
    public string CardNumberMasked { get; set; }
    public decimal Amount { get; set; }
    public DateTime TransactionDate { get; set; }
}

public class AppDbContext : DbContext
{
    public DbSet<Payment> Payments { get; set; }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlServer("Your_Connection_String_Here");
    }
}

Let’s break it down:

Payment: This is our C# class that represents the Payments table in the database.
AppDbContext: This is the EF Core class that will manage the connection and mapping between your classes and database.
DbSet: This tells EF Core: “Hey, I have a table called Payments”.

Step 3 – Create the First Migration

Now the exciting part. In the terminal, run:

Bash

dotnet ef migrations add InitialCreate

dotnet ef migrations add InitialCreate

What happens here:

EF Core scans your model and DbContext.
It creates a Migrations folder with C# files that describe the changes it will make to your database.

When I first ran this, I opened the generated migration file and realized, it was basically EF Core writing the SQL for me. That’s when I thought, “Okay, this is actually cool”.

Step 4 – Apply the Migration to the Database

After creating the migration, apply it with:

Bash

dotnet ef database update

dotnet ef database update

EF Core will now create the Payments table in your database. In my case, I refreshed SQL Server Management Studio and saw my new table sitting there, it honestly felt like magic.

Step 5 – Making Changes Later

Let’s say later you realize you need to store the MerchantName. Just add it to your model:

public string MerchantName { get; set; }

public string MerchantName { get; set; }

Then run:

Bash

dotnet ef migrations add AddMerchantName
dotnet ef database update

dotnet ef migrations add AddMerchantName
dotnet ef database update

EF Core will update only what’s needed. No need to recreate the whole database.

Rolling Back a Migration

Sometimes, mistakes happen.

If you want to revert to a previous migration:

Bash

dotnet ef database update PreviousMigrationName

dotnet ef database update PreviousMigrationName

I once pushed the wrong migration to a test environment, and rolling back saved me from spending hours fixing data manually.

Real-World Tips from My Projects

Name your migrations clearly. “AddMerchantName” is better than “Migration1”.
Don’t push broken migrations to main branch. Your teammates will hate you for it.
Test migrations in staging first, especially in systems that handle payments or financial data.

Common Errors You Might See

Connection string issues: Check if your database server is reachable.
Missing EF Core package. Install it with:

Bash

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

dotnet add package Microsoft.EntityFrameworkCore.SqlServer

Migration conflicts. Can happen in team projects if multiple people run migrations without syncing.

Conclusion – Your Turn

Running your first EF Core migration might feel intimidating, but trust me, once you see your database magically update from your C# code, you’ll wonder why you were doing SQL scripts manually before.

So open your terminal, run your first migration, and enjoy that “first table created” moment.