OPS-ONT-002 — Make schema migration a deployment gate
| Field | Value |
|---|---|
| Status | Open finding; source-verified, current live revision compatible |
| Severity | High |
| Components | sparqd/platform-stacks, sparqd/ontology |
| Associated issues | sparqd/platform-stacks#682 |
Concrete observed case
The deployed database reports Alembic revision 7f8a9b0c1d2e, matching the
deployed image head. However, the image command starts Uvicorn directly and the
Ontology KCL defines no Alembic job, init container, rollout dependency, or
post-deployment schema assertion. How the current schema reached head is not
encoded in the deployment contract.
This is not universal across platform components: OpenFGA has an explicit migration job, Airflow enables its chart migration jobs, and LTAP declares schema provisioning. Other custom services require individual inspection.
Expected condition
Every Ontology rollout declares the required schema revision, runs one idempotent migration operation before incompatible application pods become ready, blocks on failure, records the result, and follows a reviewed backward compatibility, rollback, and backup policy.
Why it matters
An image can start against an older schema and fail only when a changed route is used. Multiple Uvicorn workers or rolling replicas must not race self-migration. Manual success in the current environment is not repeatable delivery evidence.
Existing controls and workarounds
Alembic migration files and migration-focused tests exist. Operators can run Alembic manually and compare current with head. That process is not declared, ordered, or enforced by the platform stack.
Alternatives considered
- Recommended: a versioned, one-shot migration job that depends on the database and gates application rollout, followed by a revision assertion.
- Application self-migration — rejected for multi-worker and rolling-rollout race risk unless protected by a proven single-run coordination mechanism.
- Manual runbook — acceptable only as a temporary controlled release step and not the target delivery contract.
Component involvement
- Ontology owns migration compatibility, idempotency, and revision metadata.
- Platform stacks owns job ordering, failure gating, timeout, observability, and deployment postconditions.
- Database recovery must exist before destructive or non-reversible migrations.
Reproduction and verification
Follow ONT-S009.
Resolution conditions
Close when a previous supported schema is upgraded by the declared deployment flow, an injected migration failure blocks new application readiness, current equals image head afterward, and rollback/restore behavior is demonstrated.
Validation and blockers
Current live compatibility and missing orchestration are confirmed. The shared platform migration standard and Ontology's expand/contract policy require delivery and database review.