Operations
Upgrading
Move an install to a new version of Helpwren, with a backup taken first.
Before you start
- The checkout you installed from, with no uncommitted changes.
- On Supabase Cloud,
pg_dumpon your machine if you want the upgrade to back up the database. - Read the changelog for the versions you are moving across.
Upgrade
-
See what the upgrade would do. This changes nothing:
Terminal pnpm helpwren upgrade --dry-run -
Run it:
Terminal pnpm helpwren upgrade -
On Supabase Cloud, redeploy the app. Vercel deploys on every push; push the new version to the branch it builds from.
-
Check
/api/health: it answers"migrations": "current"when the database has every migration the running build expects.
The upgrade:
- pulls the new version with a fast-forward
git pull, refusing if you have uncommitted changes, then runspnpm install; - lists the migrations the database has not had yet (
supabase db push --dry-run); - asks to back up the database first and, with your yes, saves a
pg_dumpto.helpwren/backups/. With Docker it dumps from thedbcontainer; on Cloud it needspg_dumpon your machine, and otherwise reminds you to check the project's backups; - applies the migrations;
- rebuilds: with Docker it rebuilds and restarts the app and scheduler containers; on Cloud it
runs
pnpm build.
| Flag | What it does |
|---|---|
--dry-run | Shows what would happen and changes nothing |
--no-pull | Uses the code already checked out |
--backup, --no-backup | Backs up the database first, or not, without asking |
--db-url | The connection string for the migrations. Also read from SUPABASE_DB_URL |
--yes | Asks nothing, for CI |
If something goes wrong, see Backups and rolling back.
Upgrade the self-hosted Supabase stack
Moving Docker's Supabase stack to a new Supabase release is a separate, deliberate step:
- Read Supabase's self-hosting changelog.
- Change
SUPABASE_SELF_HOSTED_REFinpackages/cli/src/docker.ts. - Move
deploy/docker/supabaseaside and runpnpm helpwren install --mode dockeragain.
Data lives in named volumes, so fetching the new files never touches it.