Migrations

Your model changes as the application grows. A migration is the record of one such change: a C# file describing how to move the database from the previous shape to the new one, and how to go back.

The alternative is a folder of loose SQL scripts and a shared understanding of which have been run. That works until two people apply them in different orders, or a script is run twice, or someone changes a column by hand on a Friday. A migration removes the guesswork by recording the sequence and letting the database remember where it has reached.

Migrations are ordinary source files. They belong in version control alongside the model change that required them, they show up in a pull request, and a colleague can read one before it touches a database.

# Create a migration from the difference between your model and the last one
dotnet ef migrations add AddDepartmentBudget

# Apply everything not yet applied to the database in your connection string
dotnet ef database update

# See what exists and what has been applied
dotnet ef migrations list

# Remove the newest migration -- only if it has NOT been applied anywhere
dotnet ef migrations remove

# Produce a SQL script instead of connecting to the database
dotnet ef migrations script --idempotent --output deploy/schema.sql

• The name after add is yours to choose and it is permanent. AddDepartmentBudget tells a future reader what the file does; Migration7 tells them nothing.
• database update applies every pending migration in order. Run it twice and the second run does nothing, because the database records what it has already applied.
• migrations remove deletes the newest migration file. It is safe only while that migration exists on your machine alone. Once it has been applied or pushed, removing it means other databases and other developers disagree about history.
• The script command is how production deployments usually work: generate SQL, have someone review it, run it through your normal release process. The idempotent option makes the script safe to run against a database at any point in the sequence.
• Add --project and --startup-project when your context lives in a different project from the entry point, which is common once a solution has more than one project.

public partial class AddDepartmentBudget : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.AddColumn<decimal>(
            name: "AnnualBudget",
            table: "Departments",
            type: "decimal(18,2)",
            nullable: false,
            defaultValue: 0m);
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.DropColumn(
            name: "AnnualBudget",
            table: "Departments");
    }
}

• Up moves the database forward. Down undoes it. Both are generated for you, and both are plain C# you can read and change before anything is applied.
• The timestamp at the front of the filename fixes the order. This is why two developers adding migrations on the same day usually get a clean sequence, and why merging two branches that each added one needs a look rather than a blind accept.
• A non-nullable column added to a table with existing rows needs a default, or the statement fails. EF Core supplied 0m here. That default applies to existing rows only — it is a migration detail, not a rule your model enforces afterwards.
• Notice that Down for this migration drops the column, and therefore discards every value stored in it. Reversible in schema terms; not reversible in data terms.

ALTER TABLE [Departments] ADD [AnnualBudget] decimal(18,2) NOT NULL DEFAULT 0.0;
GO

INSERT INTO [__EFMigrationsHistory] ([MigrationId], [ProductVersion])
VALUES (N'20260214093000_AddDepartmentBudget', N'9.0.0');
GO

• One ALTER TABLE, which is what the migration described. Reading the SQL is the most direct way to know what will happen, especially for a change involving existing data.
• The second statement is how the database remembers. __EFMigrationsHistory is a small table EF Core creates, holding one row per applied migration.
• That table is why database update is safe to run repeatedly: EF Core reads the history, compares it with the migration files, and applies only what is missing.
• It is also why editing an applied migration does not help. The history records the identifier, not the contents, so a database that has the row will never run your edited version.