Migrations¶

The Tech Strategy Tool uses EF Core migrations to manage the PostgreSQL database schema. Migrations are the sole source of truth for the schema.

Overview¶

Migrations live in src/TechStrat.Infrastructure/Persistence/Migrations/
In Development mode, migrations are auto-applied on startup via db.Database.MigrateAsync()
In Production, migrations should be applied explicitly before deploying

Creating a Migration¶

When you change EF Core entity models or the TechStratDbContext, create a new migration:

dotnet ef migrations add <MigrationName> ^
  --project src/TechStrat.Infrastructure ^
  --startup-project src/TechStrat.Api ^
  --output-dir Persistence/Migrations

Windows command

The command above uses ^ for line continuation (Windows cmd). On Linux/macOS, use \ instead.

Naming conventions¶

Use descriptive PascalCase names that describe the change:

AddJiraKeyToInitiative
CreateSessionsTable
AddTargetIdIndex

Example workflow¶

Modify the entity model in Infrastructure/Persistence/
Run the migration command above
Review the generated migration file
Test by resetting the database: docker compose -f docker/docker-compose.yml down -v && docker compose -f docker/docker-compose.yml up -d
Start the app and verify the migration applies cleanly

Applying Migrations¶

Development (automatic)¶

In Development mode (ASPNETCORE_ENVIRONMENT=Development), migrations are applied automatically when the application starts:

await db.Database.MigrateAsync();

No manual intervention is needed.

Production (manual)¶

Apply migrations before deploying the new application version:

dotnet ef database update ^
  --project src/TechStrat.Infrastructure ^
  --startup-project src/TechStrat.Api

Or generate a SQL script for review:

dotnet ef migrations script ^
  --project src/TechStrat.Infrastructure ^
  --startup-project src/TechStrat.Api ^
  --output migration.sql

EF Core CLI Setup¶

Install the EF Core CLI tools globally:

dotnet tool install --global dotnet-ef

Update to the latest version:

dotnet tool update --global dotnet-ef

Verify installation:

dotnet ef --version

Common Operations¶

List migrations¶

dotnet ef migrations list ^
  --project src/TechStrat.Infrastructure ^
  --startup-project src/TechStrat.Api

Remove the last migration (if not applied)¶

dotnet ef migrations remove ^
  --project src/TechStrat.Infrastructure ^
  --startup-project src/TechStrat.Api

Warning

Only remove migrations that have not been applied to any database. Removing applied migrations corrupts the migration history.

Reset the database¶

The simplest way to reset is via Docker:

docker compose -f docker/docker-compose.yml down -v
docker compose -f docker/docker-compose.yml up -d

This destroys all data and creates an empty database. The next application startup will apply all migrations automatically.

Entity Models¶

EF Core entity models are in src/TechStrat.Infrastructure/Persistence/:

Entity	Table	Description
`EventEntity`	`events`	Append-only event log
`CheckpointEntity`	`checkpoints`	Document snapshots
`UserEntity`	`users`	User accounts
`SessionEntity`	`sessions`	Login sessions

Key indexes¶

Table	Column	Type
`events`	`sequence_number`	Unique
`events`	`target_id`	Non-unique
`checkpoints`	`sequence_number`	Unique
`users`	`username`	Unique
`sessions`	`user_id`	Non-unique

Troubleshooting¶

"No migrations were found"¶

Ensure you are specifying the correct --project and --startup-project paths.

"Build failed"¶

The EF Core CLI builds the project before generating migrations. Fix any build errors first.

Migration doesn't apply on startup¶

Ensure ASPNETCORE_ENVIRONMENT is set to Development. Auto-migration only runs in Development mode. For other environments, apply migrations manually with dotnet ef database update.