Migration Bundles, Runtime Migration Risks, Permissions, Locking, and Multi-Instance Deployments

Learning outcomes

1. The practical problem: production should not need source code and an SDK just to change schema

A deployment host may deliberately contain only the application artifacts and narrowly scoped operational tools. Installing the full .NET SDK, dotnet-ef, and source code merely to run migrations increases moving parts. A migration bundle packages EF's migration runner into a single executable generated during CI. A framework-dependent bundle needs a compatible runtime on the target; a self-contained bundle includes the runtime for a specific runtime identifier (RID).

2. Build bundles deliberately for the target topology

mkdir -p artifactsdotnet ef migrations bundle   --project src/ServiceHub.EfLab   --output artifacts/efbundle

dotnet ef migrations bundle   --project src/ServiceHub.EfLab   --self-contained   --target-runtime linux-x64   --output artifacts/efbundle-linux-x64

Do not build one platform binary and assume it is portable. The RID is an explicit deployment assumption. Pin the EF tool/package line used to create the bundle and archive the build metadata with the artifact.

3. Configuration and connection selection are deployment inputs

By default a bundle uses the application's connection configuration; Microsoft documentation warns to copy appsettings.json alongside the bundle when that is how the application supplies configuration. For real credentials, prefer secret injection or a protected --connection argument from the deployment environment rather than committing a production password to source or an artifact.

./artifacts/efbundle --connection "Data Source=servicehub-lab.db" --verbose

Command-line secrets can be visible to process inspection or logs depending on platform/runner. In production, use the deployment system’s supported secret mechanism and avoid echoing credentials. The lab connection string contains no secret.

4. Migration locking prevents simultaneous migration runners—not incompatible apps

EF Core 9 introduced migration locking for EF-driven migration application: CLI database update, bundles, and Migrate/MigrateAsync. The lock prevents multiple migration executions from modifying the schema concurrently. It does not make old and new application binaries automatically compatible with every intermediate schema state. You still need one migration owner and expand/contract compatibility where multiple versions overlap.

5. SQLite lock implementation has a real failure mode

SQLite has no native application lock like SQL Server sp_getapplock. EF creates __EFMigrationsLock and inserts a row. If a migration process is killed unexpectedly, the row/table can remain and later migration attempts can wait indefinitely. Recovery is an operational act: first prove no migration process is still active and inspect the database, then clear the abandoned lock according to provider guidance.

-- Only after verifying no migration owner is active:DROP TABLE "__EFMigrationsLock";-- Provider documentation also permits deleting rows instead:-- DELETE FROM "__EFMigrationsLock";

6. Deliberately wrong: every replica is allowed to be migration owner

Replica A startup -> MigrateAsync()Replica B startup -> MigrateAsync()Replica C startup -> MigrateAsync()All three runtime identities have ALTER/DROP permissions.

The EF lock serializes migration execution, but the topology is still poor: all runtime identities are over-privileged, rollouts can wait on schema work, and application/schema compatibility is uncontrolled. Repair it by making migration a distinct deployment stage/job with exactly one owner. Only after migration verification should application replicas progress according to the compatibility plan.

7. Compare deployment strategies instead of choosing by convenience

8. Hands-on lab: build, hash, run, and verify a bundle

1. From the migration-complete teaching branch, run has-pending-model-changes.
2. Build a framework-dependent bundle and record SHA-256 plus EF/dotnet-ef version.
3. Copy appsettings.json if the lab factory/bundle expects it, or pass the disposable connection explicitly.
4. Run the bundle against a copy of servicehub-lab.db; record applied migration output.
5. Run the same bundle again; expect “already up to date”/no missing migrations.
6. Inspect __EFMigrationsHistory.
7. Review the SQLite lock-table runbook without manufacturing an abandoned lock on valuable data.

9. Production judgment and bridge to seeding/zero downtime

Bundles are strong automated deployment artifacts when you want EF to own migration execution without installing the SDK/source on the target. They are not a substitute for schema compatibility design, least privilege, backups, or operational ownership. Generate a separate reviewed SQL script if exact DDL review is required. The final chapter lesson combines migration ownership with deterministic data initialization and expand/contract release planning.

Authoritative references

Use primary documentation when regenerating or adapting these deployment steps; migration behavior is provider- and version-sensitive.

• EF Core migrations overview
• Managing migrations
• Applying migrations
• EF Core .NET CLI tools
• SQLite provider limitations