// Create and apply an EF Core migration for a module's DbContext the FSH way (central Migrations project, per-module folder, correct --context). Use after changing entities/EF config. See .agents/rules/database.md.
| name | create-migration |
| description | Create and apply an EF Core migration for a module's DbContext the FSH way (central Migrations project, per-module folder, correct --context). Use after changing entities/EF config. See .agents/rules/database.md. |
All migrations live in one project — src/Host/FSH.Starter.Migrations.PostgreSQL — but are foldered
per module/context (Catalog/, Identity/, …), each with its own {X}DbContextModelSnapshot. The DB
is not migrated at API startup; the DbMigrator host applies it.
dotnet tool restore # dotnet-ef is pinned in .config/dotnet-tools.json
dotnet ef migrations add reads the current snapshot, which is regenerated from a build. If you skip
the build after editing entities/config, you can generate against a stale snapshot and lose changes. Also,
migrations remove rewrites the snapshot — only remove the latest, and rebuild after.
dotnet build src/FSH.Starter.slnx
Specify all three of --project (the Migrations project), --startup-project (the API host), and
--context {X}DbContext. Use --output-dir {X} so it lands in that module's folder (match the existing
folder for the context).
dotnet ef migrations add {MigrationName} \
--project src/Host/FSH.Starter.Migrations.PostgreSQL \
--startup-project src/Host/FSH.Starter.Api \
--context {X}DbContext \
--output-dir {X}
dotnet ef migrations script --idempotent \
--project src/Host/FSH.Starter.Migrations.PostgreSQL \
--startup-project src/Host/FSH.Starter.Api \
--context {X}DbContext
Check for: unintended table/column drops, non-nullable columns added without a default to an existing table, and renames surfacing as drop+add (data loss). Adjust the model or hand-edit the migration if needed.
Preferred (the canonical path — migrates the tenant catalog then each tenant's per-module schema):
dotnet run --project src/Host/FSH.Starter.DbMigrator -- apply
dotnet run --project src/Host/FSH.Starter.DbMigrator -- list-pending # to preview first
(Or, single-context local dev, dotnet ef database update --context {X}DbContext --project … --startup-project ….)
{X}/ folder in the Migrations project and the runtime project referenced from it — see add-module.dotnet ef against a BaseDbContext works because the 4-arg ctor is satisfied by the startup host's DI.dotnet tool restore done (first time)migrations add--context {X}DbContext + --output-dir {X} (lands in the right folder)apply (or ef database update for one context locally)
Add a domain entity/aggregate with EF configuration and a migration to an existing FSH module. Use when adding a new database-backed entity. Pairs with add-feature and create-migration.
Add a vertical-slice feature (command/query + handler + validator + endpoint) to an existing FSH module. Use when adding an API endpoint or business operation to a module that already exists.
Build a capability end-to-end — backend vertical slice (Contracts→handler→validator→endpoint) AND the React page wired to it. Use when delivering a user-facing feature across API + UI. Composes add-feature + add-react-page.
Publish a cross-module integration event via the Outbox and handle it idempotently in another module. Use when one module must react to something that happened in another. See .agents/rules/eventing.md.
Create a new module (bounded context) — runtime + Contracts projects, IModule, DbContext, permissions, migrations, and the four registration sites. Use when adding a distinct business domain. For a feature in an existing module, use add-feature.
Add a new permission end-to-end — server constant + endpoint gate, and (admin app) mirror it into the permissions catalog + route guard. Use when a new endpoint needs authorization. See modules/identity.md + frontend/admin.md.