Database migrations
Every Primebrick module upgrades its own database schema when it starts — schema changes are shipped as signed, ordered patches that each service applies automatically at boot. Settings → Migrations is the window into that machinery: one card per service, showing every patch it has recorded and what happened when it ran.
The page is primarily a safety net: in day-to-day operation everything on it is green and boring. It exists for the moments when a patch cannot apply — a failed migration no longer requires SSH and SQL access to fix.
What each card shows
- Service and schema — the module and the database schema it owns
(the backend owns
public). - Service status — the live health badge from the service registry. A service stuck at Migration failed is degraded: it refuses domain traffic but keeps answering this page, which is what makes remote remediation possible.
- Last boot error — shown only when the most recent migration run failed.
- Patch table — every patch the service knows about, oldest first:
| Column | Meaning |
|---|---|
| Patch | Patch name (timestamp + slug) and, when present, the error or resolution note |
| Status | pending, applied, failed, pending_review, approved, resolved_manual |
| Attempts | How many times the engine tried to apply it |
| Duration | Wall-clock time of the last successful run |
| Signed by | The key that signed the patch in the manifest |
| Applied at | When the patch last ran |
Patch statuses
- applied — ran successfully; nothing to do.
- pending — known to the manifest but not yet run (typically a patch that arrived while the service was stopped; it applies at next boot).
- pending_review — a review-gated patch: the migration engine refuses to run it until an administrator approves it. Used for destructive or ambiguous schema changes. A pending_review patch pauses everything after it, so the service reports itself degraded.
- failed — the patch ran and errored; the engine will not retry on its own.
- approved — a pending_review patch an administrator approved; it runs on the next migration pass.
- resolved_manual — an administrator marked the patch as handled outside the engine (e.g. the change was applied by hand). It is never run again.
Actions
All actions require an administrator and are available per service card:
- Retry failed — resets every
failedpatch topendingand re-runs the migration pass immediately. Use this after the underlying problem is fixed (e.g. a missing extension installed, a conflict resolved). - Approve — per-row action on a
pending_reviewpatch. Opens a dialog for an optional note, then marks the patchapprovedand re-runs migrations. Only approve a patch after reading its review comments. - Mark resolved — per-row escape hatch on
failed/pendingpatches: marks the rowresolved_manualwith your note. Use it when the change was applied by hand and the patch must never run again. - Drift check — compares the service's declared entities against the live database and reports whether the schema is clean or differences exist. Drift means the code and the database disagree — investigate before approving or retrying anything.
- Refresh — reloads the card's status on demand.
The recovery loop
When a migration fails at boot, the affected service registers itself as
migration_failed: the rest of the platform keeps working, and only that
service's domain APIs answer 503. From this page you can read the exact
error, fix the cause, then Retry failed — the service re-runs its
migrations live and returns to online without a restart. Nothing about
the failure is hidden: failed rows keep their error text and attempt count
until they succeed or are explicitly resolved.