Skip to main content
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 ClickHouse and Postgres 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 ClickHouse and Postgres 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.