---
checkId: check.postgres.migrations
plugin: stellaops.doctor.postgres
severity: warn
tags: [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
```bash
# 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:

```yaml
services:
  platform:
    environment:
      Platform__AutoMigrate: "true"
```

### Bare Metal / systemd
```bash
# 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:

```json
{
  "Platform": {
    "AutoMigrate": true
  }
}
```

### Kubernetes / Helm
```bash
# 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`:

```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