Repository navigation
docs(changelog): require a database backup before the payments migration - #267
Merged
Merged
Conversation
The unreleased work includes migration 00072, which renames two columns on `bookings` and adds `payment_provider`. Migrations run automatically at boot, so an operator only learns about it when the app starts the new image. Records it in the `[Unreleased]` section, which is what becomes the release body, so the instruction cannot be missed at the one moment it matters. Covers both deployment paths: the Litestream drill for Docker and Railway (including the `calnode.key` caveat, since the replica holds the database and not the key), and a module backup for NS8, which captures the volume and `state/calnode.env` where the key lives. No code change.
Contributor
There was a problem hiding this comment.
ℹ️ Minor suggestion only. The entry is accurate against the migration,
DEPLOY.md§6 and the NS8 packaging.
Reviewed changes
### Upgradingsection in[Unreleased]— requires a database backup before the upgrade that runs migration00072(twobookingscolumn renames pluspayment_provider), with per-path guidance for Docker/Railway (theDEPLOY.md§6 restore drill, plus thecalnode.keycaveat) and the NS8 module (volumes/calnode-data,state/calnode.env).- Accuracy checks —
00072_payment_provider_columns.sqlmatches the described renames and add, its+goose Downrestores both names and drops only the new column, the NS8 backup contents matchpackaging/ns8/README.md:92-93, and the key-file wording matchesDEPLOY.md§6 verbatim. Placing it first in[Unreleased]means the release workflow'sawkcarries it into the release body.
deepseek-v4.1-flash | 𝕏
Comment on lines
+20
to
+25
| - **Docker or Railway.** Take the backup deliberately rather than assuming a replica | ||
| exists somewhere, and prove it restores while the app is still on the old version: the | ||
| non-destructive drill in `DEPLOY.md` §6 restores to a scratch path without touching the | ||
| live database. If you run without `CALNODE_ENCRYPTION_KEY`, also copy | ||
| `/data/calnode.key`. The replica holds the database, not the key, and a restore without | ||
| it will not start. |
Contributor
There was a problem hiding this comment.
This bullet sends every non-NS8 reader to the §6 drill, but that drill only works from a configured Litestream replica: DEPLOY.md §6 says backups are off until LITESTREAM_* is set, and the standalone binary ships no Litestream or entrypoint at all. Readers in either case get told to “take the backup deliberately” with no procedure they can follow.
Technical details
# Backup guidance assumes a Litestream replica exists
## Affected sites
- `CHANGELOG.md:20-25` — the Docker/Railway bullet points at the §6 drill, which requires
`LITESTREAM_*` and `/etc/litestream.yml`.
- `DEPLOY.md:219-222` — “**Backups are OFF until you set the env vars below**”.
- `DEPLOY.md:42-48` (Standalone binary) — no Litestream, DB at `./data/calnode.db`; the
key, when not supplied via `CALNODE_ENCRYPTION_KEY`, is `./data/calnode.key`
(`internal/keyvault/secret.go:40`).
## Required outcome
- The section tells an operator without a replica how to take the backup it asks for:
stop the app, copy the SQLite file and the key file next to it (`/data/…` in a
container, `./data/…` for the binary).
## Suggested approach (optional)
- Extend this one bullet instead of adding a third: “with `LITESTREAM_*` set” → run the
§6 drill; “without a replica” → copy the database and key while the app is stopped.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

The unreleased work includes migration 00072, which renames two columns on
bookings(stripe_session_id→payment_session_id,stripe_payment_intent_id→payment_ref) and addspayment_provider.Migrations run automatically at boot, so an operator finds out when the app starts the new image. The instruction has to be in the release notes, not only in
DEPLOY.md, because the release notes are what people read before they upgrade.What this adds
An
### Upgradingsection at the top of[Unreleased], which is the section the release body is extracted from, so it cannot be lost when the version is cut.It covers both deployment paths:
DEPLOY.md§6. Includes thecalnode.keycaveat: the Litestream replica holds the database but not the key, so a restore without it will not start.volumes/calnode-dataandstate/calnode.envwhere the key lives.It also states the honest limit: the migration has a down path that restores both column names and keeps the data, but a backup is the only safety net for anything that goes wrong between the migration running and the first check that existing bookings look right.
Verification
Parsed with the same
awkthe release workflow uses, so the section is the first thing in the extracted body:No code change. No em dashes.