Self-hosting
Upgrades and rollback
Upgrading
Replace the binary and restart. Migrations are versioned, advisory-locked and run at startup, so a rolling restart across several instances is safe — one applies, the others wait.
Rolling back is not supported across a schema change
This is a product decision, stated plainly rather than left for you to discover.
Migrations are forward-only. Rolling a binary back across a version that included a migration is not supported. There is no down-migration, and an older binary meeting a newer schema is undefined behaviour, not a tested path.
We would rather say that than invent a rollback story the binary cannot honour.
What to do instead
- Take a database backup before any upgrade that includes a migration. That backup, not a binary downgrade, is your rollback.
- If an upgrade goes wrong, restore the backup and run the old binary against it.
- Do not run mixed versions against one database, except for the brief overlap of a rolling restart within a single version.
How to know whether an upgrade includes a migration
The startup log names every migration it applies:
store: applied migration 0016_custom_rule_state.sql
An upgrade that logs no applied migration lines changed no schema, and a binary rollback across it is uneventful. That log line is the thing to check, both before you plan and after you deploy.
What to back up
| Thing | Why |
|---|---|
| The Postgres database | Everything: conventions, findings, receipts, audit log. |
GARBOARD_SECRET_KEY (or your KMS key) |
Lose it and every sealed secret is permanently unopenable. |
GARBOARD_RECEIPT_KEY |
The receipt signing key. Losing it does not invalidate past receipts, but you cannot sign new ones under the same identity. |
| The GitHub App private key | Cheaper to rotate than to restore, but note it is not in the database. |
The second row is the one people miss. A database backup with no key backup restores data you cannot decrypt.