Safe workflow for adding and applying an Entity Framework Core migration in a .NET project. Use this skill when a domain model change requires a new database schema migration.
Check for uncommitted model changes — verify all relevant C# model changes are saved:
git diff -- "*.cs"
Build the solution — a clean build is required before EF Core can generate a migration:
dotnet build
Fix any compile errors before continuing.
Generate the migration — use a descriptive PascalCase name that
summarises the schema change (e.g., AddOrderItemTable,
RenameCustomerEmailColumn):
dotnet ef migrations add <MigrationName> \
--project src/Infrastructure \
--startup-project src/Api
Review the generated file — open
src/Infrastructure/Migrations/<Timestamp>_<MigrationName>.cs and verify:
Up() creates / alters exactly the intended tables and columns.Down() cleanly reverses every change in Up().Apply to the local database:
dotnet ef database update \
--project src/Infrastructure \
--startup-project src/Api
Run integration tests — confirm the schema change works end-to-end:
dotnet test --filter Category=Integration
Report — describe what changed and flag any risks (destructive changes, large tables, missing indexes).
## Migration: <MigrationName>
**Generated:** `src/Infrastructure/Migrations/<Timestamp>_<MigrationName>.cs`
### Schema changes
- <description of Up() changes>
### Rollback
- <description of Down() changes>
### Risks
- <None | description of any destructive or high-risk changes>
### Verification
- ✅ `dotnet build` — succeeded
- ✅ `dotnet ef database update` — applied successfully
- ✅ `dotnet test --filter Category=Integration` — all passed
AddShippingAddressToOrder, not JIRA-1234).migrationBuilder.Sql() in a
separate migration from schema changes.Down() is correct — EF Core sometimes generates an incomplete
rollback for complex changes.