Managing Schema Migration Conflicts

In this lesson, you will learn how to resolve the "divergent migration" problem that occurs when multiple developers generate conflicting EF Core migration files simultaneously.

Understanding the Collision

When two developers add a migration at the same time, both will create a new file in the Migrations folder with a unique timestamp (e.g., 20231027120000_AddUserEmail.cs and 20231027120005_AddProductPrice.cs). Both files will attempt to update the __EFMigrationsHistory table and the schema snapshot, leading to a merge conflict in your version control system.

How to Resolve Conflicts

The most robust strategy is to treat your migration files as immutable sequences. If you encounter a merge conflict where two different migration files share the same parent, you should not manually merge the C# code inside the files. Instead, follow this workflow:

1. Revert and Rebase: The developer who loses the race should revert their migration locally, pull the latest changes from the main branch, and then re-apply their migration.
2. Re-generate: Because the ModelSnapshot has now changed due to the incoming migrations from the team, running dotnet ef migrations add <Name> again will create a new migration that correctly identifies the previous migration as its "base" (the Migration attribute's DbContext model will be updated).

If the migration files are already committed and causing issues, you can "squash" them if necessary, but the safest approach for large teams is to use a "Migration Leader" strategy. In this pattern, only one person is responsible for merging migrations into the main branch, ensuring that the __EFMigrationsHistory table order remains linear and deterministic across all environments.

Why not merge manually?

Never attempt to manually combine the Up() or Down() methods of two different migrations into one file. The EF Core designer relies on the snapshot to determine the delta. If the snapshot metadata isn't perfectly synced with the migration sequence, dotnet ef database update will fail during deployment, leading to inconsistent database states across developer workstations.

Key Takeaway: Never manually merge C# migration code; instead, pull the latest schema changes, delete your conflicting local migration, and re-generate it against the updated snapshot to ensure a clean, linear migration history.