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

Naming conventions

Use descriptive PascalCase names that describe the change:

• AddJiraKeyToInitiative
• CreateSessionsTable
• AddTargetIdIndex

Example workflow

1. Modify the entity model in Infrastructure/Persistence/
2. Run the migration command above
3. Review the generated migration file
4. Test by resetting the database: docker compose -f docker/docker-compose.yml down -v && docker compose -f docker/docker-compose.yml up -d
5. 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

Caution

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.