fix(db): keep the PostgreSQL volume name stable across major upgrades

[FelixTJDietrich]

Motivation

#1627 renamed the self-hosted PostgreSQL volume to postgresql-data-v18 (and the preview stack's to postgres-data-v18) so a rollback would retain the PostgreSQL 17 cluster. Review flagged the residual risk that decision carries: an operator who upgrades without migrating gets a stack that comes up healthy but empty, because Compose silently creates the new volume. None of this has shipped — the PostgreSQL 18 qualification is still in the unreleased pending section — so the name can be corrected in the same release with no deployed instance ever seeing -v18.

Description

Maintainer decision: the volume goes back to its stable postgresql-data name (postgres-data in the preview stack).

• With the stable name, the skipped-migration mistake fails loudly instead: the 18+ image entrypoint detects PostgreSQL 17 data in the volume and refuses to start (major-version data directories are incompatible with the server), so nothing is silently lost. Verified empirically against postgres:18 in this PR's drill work.
• Stable volume names are the Compose norm; a version-suffixed name forces a rename (and this same reasoning) at every future major.
• scripts/postgres-major-upgrade-test.ts now rehearses the shipped flow under one stable-named volume — dump, prove PostgreSQL 18 refuses the un-migrated volume, destroy the volume, recreate it under the same name, fresh PostgreSQL 18 init, restore, and the existing partman/Liquibase/data assertions. Rollback safety moves from a retained volume to the verified dump (pg_restore --list before the destructive step). The drill passes locally end to end.
• docs/admin/backup-restore.mdx § "PostgreSQL 17 to 18" is rewritten as the stable-name operator flow (a)–(g): verified custom-format dump with an off-host copy, dc down postgres, docker volume rm <project>_postgresql-data (with docker volume ls to find the exact name), fresh start, restore, ALTER EXTENSION pg_partman UPDATE, verification. It states explicitly that step (c) destroys the old data and that skipping steps fails loudly.
• ADR 0038 gets an append-only dated amendment recording the reversal and rationale; the decisions README row is updated.
• Migration-fragment resolution: chore(db): qualify PostgreSQL 18 #1627's pending entry lives directly in MIGRATION.md's ### Next release section, which feature PRs must not edit (verify-changesets enforces it). Its "keep the PostgreSQL 17 volume until acceptance checks pass" advice is impossible under the stable-name flow, so this PR adds .migration/stable-postgres-volume-name.md, a fragment that explicitly corrects that entry (fragments are appended after the pending text under the same version heading at stamping). Note for the release assembler: when cutting the release, the older "Restore PostgreSQL 17 data into PostgreSQL 18" entry can be folded into / trimmed against this correcting fragment.
• The changeset carries the **Operators:** summary; since the -v18 name never shipped, this folds into the same release as the PostgreSQL 18 qualification.

Checklist

• pnpm run test:tooling, check:preview-stack, check:changesets, docs:lint, lint:agents, typecheck:scripts: pass
• Self-host and reference compose stacks render (docker compose config); postgres mounts postgresql-data:/var/lib/postgresql
• pnpm run test:postgres-upgrade (the rewritten drill) passes locally end to end
• The CI verify-changesets fragment validation was simulated locally and passes

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Next included review available in 4 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3e5c1746-85d7-4c94-964b-7a62045b32b7

📥 Commits

Reviewing files that changed from the base of the PR and between 398e4f4 and e619501.

📒 Files selected for processing (8)

• .changeset/stable-postgres-volume-name.md
• .migration/stable-postgres-volume-name.md
• docker/compose.app.yaml
• docker/preview/compose.app.yaml
• docs/admin/backup-restore.mdx
• docs/decisions/0038-postgresql-18-release-baseline.md
• docs/decisions/README.md
• scripts/postgres-major-upgrade-test.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📚 Documentation Preview

Preview has been removed (PR closed)

[github-actions]

🧩 Storybook Preview

Preview has been removed (PR closed)