git.stella-ops.org/docs/doctor/articles/postgres/migrations.md

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.postgres.migrations	stellaops.doctor.postgres	warn	database postgres migrations schema

PostgreSQL Migration Status

What It Checks

Connects to PostgreSQL and examines the EF Core migration history to identify pending migrations:

1. Migration table existence: checks for the __EFMigrationsHistory table in the public schema. Warns if the table does not exist.
2. Applied migrations: queries the migration history table (ordered by MigrationId descending) to determine which migrations have been applied.
3. Pending migrations: compares applied migrations against the expected set to identify any unapplied migrations. Warns if pending migrations are found.

Evidence collected: TableExists, AppliedCount, PendingCount, LatestApplied, PendingMigrations, Status.

The check requires ConnectionStrings:StellaOps or Database:ConnectionString to be configured.

Why It Matters

Pending database migrations mean the database schema does not match what the application code expects. This causes 500 errors when the application tries to access tables or columns that do not exist, or uses schema features that have not been applied. In Stella Ops, missing migrations are the number one cause of service failures after an upgrade. Services may start and appear healthy but fail on the first database operation that touches a missing table or column.

Common Causes

• New deployment with schema changes but migration not executed
• Migration was not run after a version update
• Previous migration attempt failed partway through
• Database initialized without EF Core (manual SQL scripts used instead)
• Migration history table was accidentally dropped
• First deployment to a fresh database with no migration history
• Auto-migration disabled or not configured in service startup

How to Fix

Docker Compose

# Check migration status
docker compose -f docker-compose.stella-ops.yml exec platform \
  stella db migrations status

# Apply pending migrations
docker compose -f docker-compose.stella-ops.yml exec platform \
  stella db migrate

# If auto-migration is configured, restart the service (it migrates on startup)
docker compose -f docker-compose.stella-ops.yml restart platform

# Verify migration status after applying
docker compose -f docker-compose.stella-ops.yml exec platform \
  stella db migrations list

Ensure auto-migration is enabled:

services:
  platform:
    environment:
      Platform__AutoMigrate: "true"

Bare Metal / systemd

# List pending migrations
stella db migrations list --pending

# Apply pending migrations
stella db migrate

# Verify all migrations are applied
stella db migrations status

# If auto-migration is configured, restart the service
sudo systemctl restart stellaops-platform

Edit /etc/stellaops/platform/appsettings.json to enable auto-migration:

{
  "Platform": {
    "AutoMigrate": true
  }
}

Kubernetes / Helm

# Check migration status
kubectl exec -it <platform-pod> -- stella db migrations status

# Apply pending migrations
kubectl exec -it <platform-pod> -- stella db migrate

# Or use a migration Job
kubectl apply -f - <<EOF
apiVersion: batch/v1
kind: Job
metadata:
  name: stellaops-migrate
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: stellaops/platform:latest
        command: ["stella", "db", "migrate"]
      restartPolicy: Never
EOF

Set in Helm values.yaml:

platform:
  autoMigrate: true
  migrations:
    runOnStartup: true

Verification

stella doctor run --check check.postgres.migrations

Related Checks

• check.postgres.connectivity -- migrations require a working database connection
• check.postgres.pool -- connection pool issues can cause migration failures