./tb upgrade live on a throwaway stack (Docker Desktop, Mac, arm64), and production by reading.
An upgrade is one command, ./tb upgrade <version>, which first takes a backup and then changes the version. This page describes the steps, the exit codes and the way back.
Before the upgrade
- Read the
CHANGELOG.mdof the new release. Every entry says “No migration” or names the migration and how it is reverted. For example, 0.5.3 had one migration (0036_pending_clips.sql, only a new function), and most 0.5.x releases have none. - Check that
.envhasTB_BACKUP_KEY. An upgrade without it stops, because it takes a backup first. - A migration can lock a table: plan a window.
app,workerandbackupare stopped during the upgrade anyway.
Upgrade
1
Put the files of the new release in the directory and build the image
2
Check TB_BACKUP_KEY
3
Run the upgrade
./tb upgrade does, in order:
- Takes a backup (an error stops the upgrade with exit 4 and changes nothing).
- Uses the image if it exists locally, otherwise tries
docker compose pull(a failure stops with exit 1). - Stops
app,workerandbackup. - Runs
migratewith the new image. - Copies the env file to
.env.bak-<old version>and writesTB_IMAGE_TAG=<version>. - Starts
app,workerandbackup. - Waits for
/readyz(TB_READY_WAITseconds, default 120).
Exit codes
The way back after a failure
After exit 5 or 6 (and after an error writing the env file)./tb upgrade prints the way back with your paths. Run the lines as printed:
restorehassudoin front: the backup folders belong to root, and without root./tb restoredoes not see the file and says it does not exist. Keep theTB_COMPOSE_PROJECT=... TB_ENV_FILE=...from the printed line aftersudo.- Until the restore is finished,
./tb upgraderefuses to run (exit 2) and prints the same lines, because a new backup would hold a half-migrated database. It records this in.env.upgrade-failed. - If after exit 6 the new version became ready later after all and you keep it, delete
.env.upgrade-failed. - Restore details: Backup and restore.
Limits
- An upgrade stops the service for the time of the migration.
./tb upgradedoes not build the new image: you build it (ordocker compose pullfetches it if it exists in a registry).- The way back is a restore from a backup, not a reverse migration.