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

Schema Version

This Doctor check is a post-upgrade sanity probe: it confirms that the live PostgreSQL schema looks complete and internally consistent, rather than half-migrated. It is aimed at operators verifying a deployment after an upgrade, restore, or interrupted migration.

What It Checks

Counts non-system schemas and tables, inspects the latest applied migration from the real per-schema <schema>.schema_migrations ledger (the platform migration runner’s table, NOT EF Core’s __EFMigrationsHistory) 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

How to Fix

Docker Compose

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 migration_name, applied_at FROM <schema>.schema_migrations ORDER BY applied_at DESC LIMIT 5;"

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

Bare Metal / systemd

psql -h <db-host> -U <db-user> -d <db-name> -c "SELECT COUNT(*) FROM pg_constraint WHERE NOT convalidated;"

Kubernetes / Helm

kubectl exec -n <namespace> <postgres-pod> -- psql -U <db-user> -d <db-name> -c "SELECT nspname FROM pg_namespace;"

Verification

stella doctor --check check.db.schema.version