Skip to content

docs(changelog): require a database backup before the payments migration - #267

Merged
shockalotti merged 1 commit into
mainfrom
docs/upgrade-backup-note
Nov 18, 2026
Merged

shockalotti merged 1 commit into
mainfrom
docs/upgrade-backup-note

Conversation

@shockalotti

Copy link
Copy Markdown
Contributor

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 adds payment_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 ### Upgrading section 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:

  • Docker or Railway: take the backup deliberately and prove it restores while still on the old version, using the non-destructive drill in DEPLOY.md §6. Includes the calnode.key caveat: the Litestream replica holds the database but not the key, so a restore without it will not start.
  • NS8 module: run a module backup before pulling the new image, since it captures volumes/calnode-data and state/calnode.env where 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 awk the release workflow uses, so the section is the first thing in the extracted body:

### Upgrading
- **Back up the database before upgrading.** ...

No code change. No em dashes.

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.

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ℹ️ Minor suggestion only. The entry is accurate against the migration, DEPLOY.md §6 and the NS8 packaging.

Reviewed changes

  • ### Upgrading section in [Unreleased] — requires a database backup before the upgrade that runs migration 00072 (two bookings column renames plus payment_provider), with per-path guidance for Docker/Railway (the DEPLOY.md §6 restore drill, plus the calnode.key caveat) and the NS8 module (volumes/calnode-data, state/calnode.env).
  • Accuracy checks — 00072_payment_provider_columns.sql matches the described renames and add, its +goose Down restores both names and drops only the new column, the NS8 backup contents match packaging/ns8/README.md:92-93, and the key-file wording matches DEPLOY.md §6 verbatim. Placing it first in [Unreleased] means the release workflow's awk carries it into the release body.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using deepseek-v4.1-flash | 𝕏

Comment thread CHANGELOG.md
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@shockalotti
shockalotti merged commit 0536953 into main Nov 18, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant