Skip to main content
Checked on Izumi 0.5.7, 2026-11-21: ./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.
Not checked live yet: an upgrade to a really newer release with a migration, exit codes 4, 5 and 6, and the way back after a failure. Run live and passed: ./tb upgrade from 0.5.7 to 0.5.8 (the same image with another tag, “migrations: nothing to apply”, all seven steps, .env.bak-0.5.7, TB_IMAGE_TAG=0.5.8, /readyz 200), and exit 2 for a wrong version and for a version that already runs.

Before the upgrade

  • Read the CHANGELOG.md of 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 .env has TB_BACKUP_KEY. An upgrade without it stops, because it takes a backup first.
  • A migration can lock a table: plan a window. app, worker and backup are 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

It must print 1.
3

Run the upgrade

./tb upgrade does, in order:
  1. Takes a backup (an error stops the upgrade with exit 4 and changes nothing).
  2. Uses the image if it exists locally, otherwise tries docker compose pull (a failure stops with exit 1).
  3. Stops app, worker and backup.
  4. Runs migrate with the new image.
  5. Copies the env file to .env.bak-<old version> and writes TB_IMAGE_TAG=<version>.
  6. Starts app, worker and backup.
  7. Waits for /readyz (TB_READY_WAIT seconds, default 120).
At the end it prints the old and the new version, the backup file and the applied migrations.

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:
  • restore has sudo in front: the backup folders belong to root, and without root ./tb restore does not see the file and says it does not exist. Keep the TB_COMPOSE_PROJECT=... TB_ENV_FILE=... from the printed line after sudo.
  • Until the restore is finished, ./tb upgrade refuses 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 upgrade does not build the new image: you build it (or docker compose pull fetches it if it exists in a registry).
  • The way back is a restore from a backup, not a reverse migration.

Troubleshooting