---
checkId: check.db.schema.version
plugin: stellaops.doctor.database
severity: fail
tags: [database, postgres, schema, migrations]
---
# Schema Version

## What It Checks
Counts non-system schemas and tables, inspects the latest EF migration entry when available, and warns when PostgreSQL reports unvalidated foreign-key constraints.

Unvalidated constraints usually indicate an interrupted migration or manual DDL drift.

## Why It Matters
Schema drift is a common source of runtime breakage after upgrades. Unvalidated constraints can hide partial migrations long after deployment appears complete.

## Common Causes
- A migration failed after creating constraints but before validation
- Manual schema changes bypassed startup migrations
- The database was restored from an inconsistent backup

## How to Fix

### Docker Compose
```bash
docker compose -f devops/compose/docker-compose.stella-ops.yml exec postgres psql -U stellaops -d stellaops -c "SELECT conname FROM pg_constraint WHERE NOT convalidated;"
docker compose -f devops/compose/docker-compose.stella-ops.yml exec postgres psql -U stellaops -d stellaops -c "SELECT \"MigrationId\" FROM \"__EFMigrationsHistory\" ORDER BY \"MigrationId\" DESC LIMIT 5;"
```

Re-run the owning service with startup migrations enabled after fixing the underlying schema issue.

### Bare Metal / systemd
```bash
psql -h <db-host> -U <db-user> -d <db-name> -c "SELECT COUNT(*) FROM pg_constraint WHERE NOT convalidated;"
```

### Kubernetes / Helm
```bash
kubectl exec -n <namespace> <postgres-pod> -- psql -U <db-user> -d <db-name> -c "SELECT nspname FROM pg_namespace;"
```

## Verification
```bash
stella doctor --check check.db.schema.version
```

## Related Checks
- `check.db.migrations.failed` - failed migrations are the most common cause of schema inconsistency
- `check.db.migrations.pending` - verify history after cleanup