Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.tensorzero.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers how to upgrade the TensorZero Gateway, run database migrations, and perform zero-downtime upgrades.

​
Before you upgrade

1

Check the release notes

Review the release notes on GitHub for any breaking changes or special migration instructions.
2

Back up your databases

We recommend backing up your Postgres and ClickHouse databases according to your provider’s backup procedures.

​
Upgrade the TensorZero Gateway

The TensorZero Gateway is stateless: it does not store any data locally. This means you can upgrade it by simply replacing the running container with a new one. The gateway handles SIGTERM gracefully, so in-flight requests will complete before shutdown.
1

Update the image tag

Update the gateway image tag (e.g. in your docker-compose.yml, Helm values, or deployment manifest) to the desired version.
2

Run database migrations

Run any required Postgres and ClickHouse migrations before starting the new gateway. Valkey (Redis) does not require any migrations.
Rollback database migrationsMigrations are expected to work smoothly, but rare issues can happen.
  • ClickHouse: The gateway logs manual rollback instructions if a migration fails.
  • Postgres: Rollback instructions are not available at the moment.
If rollbacks are not feasible, restore the database from a backup.
3

Restart the gateway

Restart the gateway with the new image.
Zero-downtime UpgradesBecause the gateway is stateless, you can run old and new instances side-by-side behind a load balancer. Run migrations first, start new instances, verify they’re healthy via /health, then drain and shut down the old ones.
4

Verify the upgrade

curl http://localhost:3000/status

​
Upgrading the TensorZero UI

The TensorZero UI follows the same versioning as the gateway. To upgrade, update the image tag and restart. The UI does not require any database migrations. See Deploy the TensorZero UI for more details.