Upgrading

TotalBase

An upgrade is a new image and a restart:

1. Back up the database, the files volume, and check you have the master key. See Backup and restore.
2. Deploy the new version: the new image's tag (totalbase/totalbase:<version>), then docker compose pull and docker compose up -d. The release notes on GitHub say what changed.
3. Start it. It applies pending migrations to the totalbase schema, each in its own transaction, before taking requests.
4. Check /health/ready.

If a migration fails, that migration is rolled back and the server stops without taking requests; the migrations before it stay applied. Fix the cause and start again, or restore the backup to go back. There are no automatic downgrades: returning to an older version always means restoring the backup.

Applied migrations are verified on every start; one changed after it was applied stops startup with MIGRATION_CHECKSUM_MISMATCH.

Migrations only touch the totalbase schema, never your own. Columns, indexes and constraints you added to totalbase.users are kept.

PostgreSQL

Upgrading PostgreSQL to another supported major version (15 to 18) is PostgreSQL's own procedure: pg_upgrade, a dump and restore, or your managed service's upgrade. Stop TotalBase during it, then start it against the upgraded database. Read the PostgreSQL release notes for changes that affect your own SQL.

TotalBase checks the major version on start and refuses one outside 15-18.

Next steps

• Deployment.