Database Migrations in Deployments

During a rolling update, old and new versions of the API run side by side against one database, and a rollback runs the old version against the new schema. So two questions decide every migration: where it runs, and whether both versions of the code survive it.

Where migrations run

Approach	Good	Risk
Database.MigrateAsync() at app start-up	Simple; fine for development and one-replica tools	Every replica tries at once; the app needs DDL rights; a failing migration crash-loops every pod; long migrations fail startup probes
Init container per pod	Runs before the app container	Runs once per pod per rollout; still DDL rights in the app pod
A Job before the rollout (pipeline step, Helm pre-upgrade hook, Argo sync wave)	Once per release, own credentials, visible logs, failure stops the deploy	The schema must suit the code that is still running
Reviewed SQL script (dotnet ef migrations script --idempotent)	DBA review, regulated environments	A manual step that can drift

Choose the Job. The migrator connects as a role that can change the schema; the API's role can only read and write rows, so a SQL injection in the API cannot drop a table. EF Core also takes a database lock while migrating so concurrent Migrate calls do not apply the same migration twice, but that only serialises the race: the waiting pods still sit unready.

Migration bundles

dotnet ef migrations bundle --self-contained -r linux-x64 -o efbundle compiles the migrations into one executable. It needs no SDK and no source code at run time, applies only migrations missing from __EFMigrationsHistory, reads the connection string from the startup project's configuration (supply ConnectionStrings__Shop from a Secret; --connection also works but puts the password in the process list), and exits non-zero on failure so the Job fails and the pipeline stops before new pods start. Bundles are built by the EF tools, which create your DbContext through the app's host or an IDesignTimeDbContextFactory; a factory avoids running start-up code that calls other services.

Expand and contract

Renaming Customers.Name to FullName produces a single RenameColumn, and every old pod fails with "column does not exist" the moment it runs. Split breaking changes across releases:

1. Expand (release N): add a nullable FullName, backfill it in batches outside the ALTER's transaction, write both columns, read the new one with a fallback.
2. Switch (release N+1): read and write only FullName. Old pods kept writing only Name after the first backfill, leaving NULL or stale FullName values, so once no release N-1 pod remains, re-run the batched backfill (WHERE "FullName" IS NULL OR "FullName" <> "Name") before making it required.
3. Contract (release N+2, once N can no longer be rolled back to): drop Name.

Safe in one step: new tables, nullable columns, columns with a default, new indexes. Needs expand and contract: renames, drops, type changes, a new NOT NULL column without a default.

Locks in PostgreSQL

ALTER TABLE takes an ACCESS EXCLUSIVE lock and holds it until its transaction commits. Queued behind one long transaction, it blocks every query on the table, and the API stalls; a backfill in the same transaction keeps the table locked for its whole run. Set lock_timeout in the migration so it fails fast and can be retried, keep backfills in batches, and create indexes with CREATE INDEX CONCURRENTLY, which cannot run inside a transaction (suppressTransaction: true).

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Infrastructure;
using Microsoft.EntityFrameworkCore.Migrations;

public class Customer
{
    public int Id { get; set; }
    public string Email { get; set; } = "";

    // Release N (expand): both columns exist. Old pods read Name, new pods read FullName ?? Name.
    public string Name { get; set; } = "";
    public string? FullName { get; set; }

    public string DisplayName => FullName ?? Name;
}

public class ShopDbContext(DbContextOptions<ShopDbContext> options) : DbContext(options)
{
    public DbSet<Customer> Customers => Set<Customer>();
}

[DbContext(typeof(ShopDbContext))]
[Migration("20261020093000_AddCustomerFullName")]
public partial class AddCustomerFullName : Migration
{
    protected override void Up(MigrationBuilder migrationBuilder)
    {
        // Fail fast instead of queueing behind a long transaction and blocking all reads.
        migrationBuilder.Sql("SET lock_timeout = '5s';");

        migrationBuilder.AddColumn<string>(
            name: "FullName",
            table: "Customers",
            type: "character varying(200)",
            maxLength: 200,
            nullable: true);

        // Batched backfill outside the ALTER's transaction: each batch commits and releases its row locks.
        migrationBuilder.Sql("""
            DO $$
            DECLARE updated integer;
            BEGIN
              LOOP
                UPDATE "Customers" SET "FullName" = "Name"
                WHERE "Id" IN (SELECT "Id" FROM "Customers" WHERE "FullName" IS NULL LIMIT 5000);
                GET DIAGNOSTICS updated = ROW_COUNT;
                EXIT WHEN updated = 0;
                COMMIT;
              END LOOP;
            END $$;
            """, suppressTransaction: true);

        // Cannot run inside the migration transaction.
        migrationBuilder.Sql(
            """CREATE INDEX CONCURRENTLY IF NOT EXISTS "IX_Customers_FullName" ON "Customers" ("FullName");""",
            suppressTransaction: true);
    }

    protected override void Down(MigrationBuilder migrationBuilder)
    {
        migrationBuilder.Sql("""DROP INDEX CONCURRENTLY IF EXISTS "IX_Customers_FullName";""", suppressTransaction: true);
        migrationBuilder.DropColumn(name: "FullName", table: "Customers");
    }
}

apiVersion: batch/v1
kind: Job
metadata:
  name: orders-db-migrate-1-5-0
  annotations:
    helm.sh/hook: pre-install,pre-upgrade
    helm.sh/hook-delete-policy: before-hook-creation
spec:
  backoffLimit: 0
  activeDeadlineSeconds: 600
  ttlSecondsAfterFinished: 86400
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: registry.example.com/shop/orders-migrator:1.5.0
          env:
            - name: ConnectionStrings__Shop
              valueFrom:
                secretKeyRef:
                  name: orders-migrator
                  key: connection-string
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 256Mi

# syntax=docker/dockerfile:1
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
RUN dotnet tool install --global dotnet-ef --version 10.0.13
ENV PATH="${PATH}:/root/.dotnet/tools"
COPY . .
RUN dotnet ef migrations bundle \
        --project src/Orders.Data --startup-project src/Orders.Api \
        --self-contained -r linux-x64 -o /out/efbundle

FROM mcr.microsoft.com/dotnet/runtime-deps:10.0-noble-chiseled
COPY --from=build /out/efbundle /app/efbundle
ENTRYPOINT ["/app/efbundle"]

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Diagnostics.HealthChecks;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<ShopDbContext>(o =>
    o.UseNpgsql(builder.Configuration.GetConnectionString("Shop")));
builder.Services.AddHealthChecks()
    .AddCheck<SchemaVersionCheck>("schema-version", tags: ["ready"]);

var app = builder.Build();
app.MapHealthChecks("/health/ready", new() { Predicate = r => r.Tags.Contains("ready") });
app.Run();

public class ShopDbContext(DbContextOptions<ShopDbContext> options) : DbContext(options);

// The new pods only report ready once the Job has applied every migration they were built with.
sealed class SchemaVersionCheck(ShopDbContext db) : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken ct)
    {
        var pending = (await db.Database.GetPendingMigrationsAsync(ct)).ToList();
        return pending.Count == 0
            ? HealthCheckResult.Healthy()
            : HealthCheckResult.Unhealthy($"{pending.Count} migration(s) not applied: {pending[^1]}");
    }
}