Database governance built for humans and agents — controlling changes and access across every major database.
Upgrade guidance for HA-aware Bytebase deployments
This runbook focuses on upgrade-time checks for environments that may run Bytebase with more than one active replica.
Scope
- Covers operator checks before, during, and after an upgrade.
- Applies to the current runtime behavior in this repository.
- Does not introduce a new deployment mechanism.
The bundled Helm chart still deploys a single replica by default, so HA rollouts remain operator-managed outside the chart.
Before you upgrade
- Confirm the current topology.
- Call
GET /v1/actuator/infoand captureversion,externalUrl, andreplicaCount.
- Call
- Confirm whether HA is licensed.
- Call
GET /v1/subscriptionand verify thehafield.
- Call
- Protect the metadata database.
- Take the backup or snapshot your standard operating procedure requires before upgrading Bytebase.
- Confirm shared configuration is consistent.
- Every HA replica should start with
--ha, use the samePG_URL, and keep the same external URL during the upgrade.
- Every HA replica should start with
- Make sure nothing stops a migrating server.
- Bytebase opens its HTTP port only after metadata migrations finish, so
/healthzfails until then. - A readiness probe or a load balancer health check that only removes the server from traffic is safe.
- A liveness probe, an orchestrator that replaces unhealthy tasks (such as an ECS service behind a load balancer), or a deploy that rolls back on timeout (such as
helm upgrade --atomic) sends SIGTERM mid-upgrade. Give each a grace period or timeout above the expected migration time.
- Bytebase opens its HTTP port only after metadata migrations finish, so
Helm chart behavior during upgrades
The chart README uses helm upgrade for version and configuration changes, and that is still the correct command.
However, the chart currently renders a single-replica StatefulSet. Upgrading the chart does not enable an HA topology and does not add a chart value for running multiple Bytebase application replicas.
If you operate multiple Bytebase servers today, treat that topology as operator-managed and keep the upgrade procedure for those extra replicas in your own platform tooling.
Multi-replica upgrade guidance
If you operate multiple Bytebase replicas outside the bundled chart:
- Only keep multiple active replicas if HA is licensed.
- Without
ha: true, Bytebase logs HA restriction warnings and background runners skip work when more than one replica is active.
- Without
- Keep HA startup arguments consistent across replicas.
- Start each replica with
--haand the same shared external PostgreSQLPG_URLbefore beginning the rollout.
- Start each replica with
- Prefer a rolling replacement instead of a full stop/start.
- Replace replicas gradually with your orchestrator so at least one healthy replica remains available.
- Wait for replica health to settle between steps.
- After each rollout step, check
GET /v1/actuator/infoand confirmreplicaCountmatches your expectation.
- After each rollout step, check
- Watch logs during the rollout.
- Investigate any HA-license warnings before continuing to the next replica.
Single-replica upgrade guidance
If your environment uses only the bundled Helm chart with its default topology:
- Run
helm upgradewith the new Bytebase version or configuration. With--waitor--atomic, set--timeoutabove the expected migration time. - Wait for the single StatefulSet replica to become ready. It stays unready while Bytebase migrates the metadata database, and the chart does not restart it.
- Verify the updated version via
GET /v1/actuator/info.
After the upgrade
Validate the following before closing the change:
GET /v1/actuator/inforeturns the expectedversion.GET /v1/actuator/inforeturns the expectedreplicaCount.GET /v1/subscriptionstill shows the expectedhavalue.- Logs do not show
multiple replicas detected ... but HA is not enabled in license. - Background operations resume normally after the rollout window.
When to stop the rollout
Pause the upgrade and investigate if any of the following occur:
replicaCountdoes not recover to the expected value.- Replicas disagree on the external URL or metadata database configuration.
- HA-license warnings appear in a topology that is supposed to stay multi-replica.