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.
Prerequisites
Section titled “Prerequisites”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.
Publication procedure
Section titled “Publication procedure”- 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.
- 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.
- Follow the installed-broker and shared
toolora-db-backup.servicepath in the owning runbook. Verify the newly completed backup/preflight result without printing connection secrets or creating root-owned home-directory state. - 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.
- 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.
- 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.
- Observe versions/readiness and verify the affected authorized scenario. Keep migration success separate from application and provider acceptance.
State and failure reference
Section titled “State and failure reference”| 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 |
Recovery and verification limits
Section titled “Recovery and verification limits”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.