How do you apply EF Core migrations safely in a CI/CD pipeline using dotnet ef, and why not just call Database.Migrate() at application startup?

1. The pieces dotnet ef needs

2. How dotnet ef creates your DbContext

 dotnet ef migrations add AddCustomerAbn --project Data --startup-project Api
        |
        v
  1. dotnet build Api (which builds Data)
        |
        v
  2. Load Api's assembly plus Microsoft.EntityFrameworkCore.Design
        |
        v
  3. Create the DbContext, trying in this order:
     a) An IDesignTimeDbContextFactory<T> in the startup or migrations
        project                                   --> use it
     b) The app's host (WebApplication.CreateBuilder / CreateHostBuilder)
        --> run Program up to building the host, resolve T from DI
     c) A parameterless constructor on T          --> new it up
        |
        v
  4. Compare the current model with the model snapshot
     (Migrations/<Context>ModelSnapshot.cs)
        |
        v
  5. Write <timestamp>_AddCustomerAbn.cs, its .Designer.cs,
     and an updated snapshot

Step 3b is why design-time commands can fail in CI: building the host runs your Program.cs, which may try to read Key Vault, connect to a message broker or validate options. A design-time factory (3a) avoids all of that and gives the tool only what it needs.

If you must keep 3b, you can detect design time in Program.cs with EF.IsDesignTime (EF Core 9 and later) and skip startup work such as seeding or calling external services.

3. What a migration is made of

The database records applied migrations in the __EFMigrationsHistory table (columns MigrationId and ProductVersion). That table, not the files, is what decides which migrations still need to run.

4. The four ways to apply migrations

Idempotent script

Without --idempotent, the script assumes the database is at a specific starting migration (by default, empty). With it, every migration is wrapped in a check against the history table, for example on SQL Server:

IF NOT EXISTS (SELECT * FROM [__EFMigrationsHistory]
               WHERE [MigrationId] = N'20261022010203_AddCustomerAbn')
BEGIN
    ALTER TABLE [Customers] ADD [Abn] nvarchar(11) NULL;
END;

So the same script is safe against a database at any earlier version. You can also script a range: dotnet ef migrations script AddOrders AddCustomerAbn produces only the changes between those two migrations.

Migration bundle

A bundle is a small executable that contains your compiled migrations, EF Core and the provider. It applies pending migrations, the same way database update would, but without the SDK, the source code or dotnet-ef on the deploy agent.

./efbundle --connection "$BILLING_DEPLOY_DB"          # apply all pending
./efbundle 20261001000000_AddOrders --connection ...  # migrate to a specific one
./efbundle --verbose --connection ...                  # print the SQL it runs

Build it for the deploy agent's platform (-r linux-x64 or -r win-x64) and with --self-contained if the agent has no .NET runtime.

5. Why not call Database.Migrate() at startup

  6 pods start together
  pod1 --Migrate()--> takes migration lock, runs CREATE INDEX (8 min)
  pod2 --Migrate()--> waits for lock ...
  pod3 --Migrate()--> waits for lock ...
  ...
  readiness probes time out --> orchestrator restarts pods --> they wait again

Since EF Core 9, Migrate() also throws if the model has changes with no migration (the PendingModelChangesWarning is an error by default). That is helpful, but it means a forgotten migration is discovered at production startup instead of in CI.

6. Pipeline shape

  BUILD (once)                              DEPLOY (per environment)
  -------------------------------           ----------------------------------
  dotnet tool restore                       download artefacts
  dotnet build -c Release                   approval gate (prod)
  dotnet ef migrations                      ./efbundle --connection "$DB"
     has-pending-model-changes  <- gate        (runs as deploy identity)
  dotnet ef migrations bundle               failed? stop here, app unchanged
  dotnet ef migrations script               deploy new app version
     --idempotent  (for review)             smoke tests
  publish app + efbundle + migrate.sql

Build the bundle once and promote the same file through test, staging and production. The connection string comes from the pipeline's secret store (an Azure Key Vault-linked variable group, GitHub environment secrets) at deploy time, never from the repo.

7. Backward-compatible changes: expand and contract

During a rolling deploy, old and new app versions run against the same database. Every migration must therefore work with the version currently running.

To rename Phone to MobileNumber with no downtime:

EF scaffolds a property rename as RenameColumn, and some renames (or type changes) as drop and add, which loses data. Read every generated migration before you commit it.

8. Risky operations to look for in review

9. Transactions, failure and rollback

• EF Core runs each migration in a transaction where the provider supports transactional DDL. On SQL Server and PostgreSQL a failure usually rolls back that migration cleanly. MySQL does not support transactional DDL, so a failure can leave a half-applied migration.
• Some statements can't run in a transaction (for example CREATE INDEX CONCURRENTLY on PostgreSQL). Use migrationBuilder.Sql("...", suppressTransaction: true) and plan for partial failure.
• Prefer rolling forward: write a new migration that corrects the problem. Down() methods are rarely tested and often lose data.
• If you do need a reverse script, generate it explicitly, for example dotnet ef migrations script AddCustomerAbn AddOrders (from a later migration to an earlier one), and review it.
• Before a destructive release, confirm a backup or point-in-time restore window (Azure SQL keeps 7 to 35 days by default depending on tier).

10. Diagnosing common failures

Add --verbose to any dotnet ef command to see the build output, which context it picked and the full stack trace.

11. Security

• Use two identities: a deployment identity with DDL rights, used only by the migration step, and an app identity limited to data access (for example db_datareader and db_datawriter, or specific grants).
• Prefer managed identities or workload identity federation over passwords in connection strings.
• Never commit connection strings in a design-time factory. Read them from an environment variable or user secrets.
• Keep the generated SQL script as a build artefact. It is your audit trail of what changed in production.

12. .NET 11 awareness

EF Core 11 is due with .NET 11 in November 2026, as a standard-term (STS) release, and is at the preview and release-candidate stage now. Expect the same dotnet ef commands and the same pipeline shape. Check the EF Core 11 "what's new" and breaking-changes pages before upgrading, and keep dotnet-ef in step with the packages. Production systems should stay on EF Core 10 (LTS) until you have tested the upgrade.

13. Try it yourself

1. Create a Web API (Api) and a class library (Data) with a DbContext that uses SQLite. Reference Microsoft.EntityFrameworkCore.Design from Api.
2. Run dotnet new tool-manifest and dotnet tool install dotnet-ef so the tool is pinned locally.
3. Run dotnet ef migrations add Init --project Data --startup-project Api and open the three generated files.
4. Run dotnet ef migrations script --idempotent -o migrate.sql and find the IF NOT EXISTS (or SQLite equivalent) checks.
5. Build a bundle with dotnet ef migrations bundle --project Data --startup-project Api -o efbundle, then run ./efbundle --connection "Data Source=app.db" twice. The second run applies nothing.
6. Add a property to an entity without adding a migration, and run dotnet ef migrations has-pending-model-changes. Note the non-zero exit code that would fail a CI step.
7. Rename a property, add a migration and check whether EF generated RenameColumn or a drop and add.

namespace Billing.Data;

// Used only by dotnet ef at design time; never by the running app.
public sealed class BillingContextFactory : IDesignTimeDbContextFactory<BillingContext>
{
    public BillingContext CreateDbContext(string[] args)
    {
        var connection = Environment.GetEnvironmentVariable("BILLING_DESIGN_DB")
            ?? "Server=(localdb)\\mssqllocaldb;Database=BillingDesign;Trusted_Connection=True";

        var options = new DbContextOptionsBuilder<BillingContext>()
            .UseSqlServer(connection)
            .Options;

        return new BillingContext(options);
    }
}

# Azure Pipelines (excerpt)
- script: dotnet tool restore
- script: dotnet ef migrations has-pending-model-changes --project src/Billing.Data --startup-project src/Billing.Api
  displayName: Fail if the model has no matching migration
- script: >
    dotnet ef migrations bundle
    --project src/Billing.Data --startup-project src/Billing.Api
    --configuration Release --self-contained -r linux-x64
    -o $(Build.ArtifactStagingDirectory)/efbundle
  displayName: Build migration bundle

# Deploy stage, running under the deployment service connection
- script: ./efbundle --connection "$(BillingDbDeployConnection)"
  displayName: Apply migrations before swapping slots