skip to content

In EF Core 10, what does dotnet ef database update do, and how do you move a database back to an earlier migration?

level: juniorimportance: must knowfreq 70%

answer

  1. __EFMigrationsHistory lists what ran
  2. unapplied migrations in id order
  3. a migration name as the target
  4. 0 reverts everything
  5. --connection overrides the configured string

basics

~20 s

It applies every migration not yet recorded in __EFMigrationsHistory, in id order, and adds a history row for each. Passing a migration name moves the database to that point, running Down on newer migrations; 0 reverts them all.

solid answer

~40 s

`dotnet ef database update` builds the project, creates the `DbContext` the way the design-time tools do, and uses its connection string unless `--connection` overrides it. It creates the database and the `__EFMigrationsHistory` table if they are missing, takes EF Core's migration lock, then applies each migration whose id is not in the history table, in id order, inserting a row as each one completes; afterwards it runs the `UseSeeding` delegate. With a target, `dotnet ef database update AddPayslipTaxCode`, it applies up to that migration or, if newer ones are applied, runs their `Down` methods newest first; `0` reverts every migration. Rolling back can lose data that `Down` drops, and the command needs the SDK and the source, so it is a development and test tool rather than a production deployment step.

code

bash · 11 lines
bash
# apply everything that is pending
dotnet ef database update

# move to a specific migration (forward or back)
dotnet ef database update AddPayslipTaxCode

# revert every migration, keep the database
dotnet ef database update 0

# target another database
dotnet ef database update --connection "Host=localhost;Database=payroll_test;Username=payroll"

go deeper

for a junior

Know that database update applies pending migrations, that a migration name moves the database to that point, and that 0 reverts every migration.

for a middle

Explain the history table, how unapplied ids are found and ordered, the migration lock, the seeding step, and why naming a target skips the pending-model check.

for a senior

Treat rollbacks as data-affecting deployments, keep the tool to development and test databases, and move production to reviewed scripts or bundles.

for a principal

Define the rollback policy: when a forward fix beats a revert, what rehearsals a revert needs, and which identities may change schema in each environment.

## What the command does `dotnet ef database update` is the EF Core command-line way to bring a database up to date with the migrations in your project. For a payroll service with `PayrollDbContext` on PostgreSQL, one run goes through these steps: 1. Build the target and startup projects and create the `DbContext` at design time (through an `IDesignTimeDbContextFactory<TContext>`, the app's services, or a parameterless constructor). 2. Take the connection string from that context, which is what `AddDbContext` or `OnConfiguring` configured, unless `--connection` supplies another one. 3. Create the database if it does not exist, and create the **migrations history table** `__EFMigrationsHistory` if it is missing. 4. Since EF Core 9, acquire a **migration lock**, so two runs cannot apply migrations at the same time. On Npgsql it is a `LOCK TABLE` on the history table. 5. Read the applied ids, compute what to apply or revert, and execute it. In EF Core 10 each migration runs in its own transaction; a history row is inserted with the migration's `Up` operations. 6. Run the configured `UseSeeding` delegate, even when nothing was applied. When migrating to the latest migration, EF Core first checks that the model has no changes missing from a migration and throws if it has; that check is skipped when you name a target. ## Targets: forward, back, or all the way down | Command | Effect | |---|---| | `dotnet ef database update` | apply every unapplied migration | | `dotnet ef database update AddPayslipTaxCode` | apply up to and including `AddPayslipTaxCode`, or revert every applied migration newer than it | | `dotnet ef database update 0` | revert every applied migration, newest first | Reverting means running each migration's `Down` in reverse order and deleting its history row. `Down` is code that was scaffolded when the migration was added; if it drops a column, the data in that column is gone. A rollback on a database holding real payroll data therefore needs the same review as a forward change. ## How the history table drives everything `__EFMigrationsHistory` has one row per applied migration: the `MigrationId` (timestamp and name, such as `20261006090000_AddPayslipTaxCode`) and the `ProductVersion` of EF Core that applied it. The command: - applies a migration only if its id is missing, so running it twice is harmless; - applies **every** unapplied id, including an older-dated one that arrived late from a merged branch; - never inspects the real schema, so a table someone created by hand makes the matching migration fail. ## Choosing where the command belongs - **Local development:** the usual way to apply migrations to your own database. - **Tests and throwaway environments:** quick and scriptable; `--connection` points it at another database. - **Production:** a poor fit. It needs the .NET SDK, the dotnet-ef tool and the source tree on the machine that runs it, and it executes SQL nobody reviewed. A **migration bundle** or an **SQL script** generated in CI covers that case. ## Mistakes that come up - **Running against the wrong database.** The design-time tools use the `Development` environment unless `ASPNETCORE_ENVIRONMENT` or `DOTNET_ENVIRONMENT` is set, so the connection string comes from development settings. - **Expecting `database update` to undo files.** It changes the database only; deleting migration code is `dotnet ef migrations remove`. - **Confusing `0` with dropping the database.** `0` keeps the database and reverts migrations; `dotnet ef database drop` deletes the database. - **Rolling back past a data move.** If a migration transformed data, its `Down` may not restore the original values. ## Checking state before and after - `dotnet ef migrations list` connects to the database and marks every migration it has not applied with `(Pending)`; `--no-connect` lists them without the check. - `dotnet ef migrations script AddPayslipTaxCode AddPayRunAudit` prints the SQL of a step before you apply it, which is the quickest way to see what a rollback would drop. - In code, `GetAppliedMigrationsAsync()` and `GetPendingMigrationsAsync()` on `context.Database` return the same information as lists of ids. - `--no-build` skips building the projects when CI has just built them; with stale binaries it applies the migrations those binaries contain, not the ones in your editor.

  • Does dotnet ef database update compare the model with the live schema before applying?
    No. It reads only `__EFMigrationsHistory` to learn which migration ids ran, and it compares the model with the migrations' snapshot to detect changes nobody captured in a migration. If a table was created by hand, the migration that creates it fails when it runs.
  • What happens when a newer migration's Down drops a column you roll back past?
    `Down` runs exactly as scaffolded, so the column and its values are dropped and the history row is deleted. Rolling forward again recreates an empty column. Data that matters needs a `Down` that preserves it, a backup, or a forward corrective migration instead of a rollback.

  • dotnet ef database update compares the model with the live schema and fixes differences.
  • database update 0 drops the database.
  • Rolling back to an earlier migration never loses data, because Down mirrors Up.
  • database update skips an unapplied migration whose id is older than the last applied one.
  • Running database update on production servers is the recommended deployment path.