Skip to content

Publish compatible database changes

Schema publication changes a persistent shared database before dependent application components become current. It requires a coherent forward history, exact candidate and upgrade evidence, a fresh backup prerequisite and explicit writer handling. The runbook’s production name is an infrastructure label; Toolora remains pre-launch.

Create migrations with make migration. A migration already on main is immutable; new versions sort after the newest main migration and never manage their own transaction. Regenerate Supabase types with make types. Previously authorized hash-pinned historical amendments are already applied and confer no permission to amend them again.

The candidate must satisfy the current reviewed-main and green-CI contract. Upgrade evidence must match repository, workflow, artifact digest, actual starting migration prefix and full source tree. The published-baseline file records the declared starting prefix; it is not automatically the newest migration filename. Test levels explains clean-build versus upgrade proof.

  1. Inspect the exact candidate and all pending migrations, including changes inherited from main. Run the local focused checks, clean-schema/type checks and applicable upgrade rehearsal on its disposable stack.
  2. Use the operator’s read-only check to inspect prerequisites. Resolve missing source provenance, schema status or upgrade evidence before the mutating release. An old successful backup receipt is not a fresh prerequisite.
  3. Follow the installed-broker and shared toolora-db-backup.service path in the owning runbook. Verify the newly completed backup/preflight result without printing connection secrets or creating root-owned home-directory state.
  4. Acquire the shared release lock and preserve the currently published component identities. The procedure stops the API writer and invalidates durable schema-publication status before applying SQL. Identify other direct writers; stopping the API does not stop every possible database client.
  5. Apply every pending forward migration through the pinned CLI and approved connection wrapper. The wrapper supplies credentials without putting a password in a command argument. Do not select only one convenient migration from a pending sequence.
  6. Compare the migration ledger and semantic schema catalogue, then refresh publication status. Publish the compatible API with forward-only failure handling and then the frontend as required. Unchanged components and a no-SQL release follow the tool’s guarded skip paths.
  7. Observe versions/readiness and verify the affected authorized scenario. Keep migration success separate from application and provider acceptance.
Boundary Expected state Failure response
Before SQL Exact candidate, fresh prerequisites and valid lock Refuse before pausing/publishing if prerequisites disagree
During SQL Applied ledger reflects actual completed migrations Stop and inspect; earlier migrations may already have committed
After SQL Catalogue/ledger and durable publication status agree Do not publish against unverified schema
API publication Compatible writer and normal readiness Forward-only failure keeps incompatible old writer from restarting
Business check Named affected outcome at observed versions Record a concrete unresolved issue rather than claiming full acceptance

A sequence of migrations is not one global transaction. After a partial failure, inspect the actual ledger and objects before preparing a forward correction. Do not rewrite history, mark unapplied files as applied, reverse data casually or restart an incompatible prior application.

schema_catalogue.py compares semantic object definitions; supabase db diff cannot reliably represent the entire schema. A matching catalogue and ledger establish schema parity within that comparison, not data correctness, preserved Storage, Auth recovery or safe provider state. Recovery owns the broader acceptance boundary.

For a synthetic added column, a clean build proves a fresh database can reach the candidate. Upgrade rehearsal proves the supported starting prefix can reach it. Neither proves the shared database was migrated. Record the exact candidate, evidence identity, applied prefix, component versions and affected result. Publication and evidence preserve those distinctions.