High Availability

Bytebase supports high availability (HA) for self-hosted deployments.

In HA mode, you run multiple Bytebase replicas behind the same external endpoint. The replicas coordinate through the shared metadata PostgreSQL database, so scheduled work such as rollout tasks, plan checks, schema sync, and cancellation handling remains safe across replicas.

Requirements

• Use an external PostgreSQL database for Bytebase metadata
• Start every replica with the --ha flag
• Put all replicas behind the same load balancer / ingress / service
• Configure the same External URL for the deployment
• Use a license with HA enabled

HA mode does not work with Bytebase’s embedded PostgreSQL. If PG_URL is not set, Bytebase will refuse to start in HA mode.

How It Works

• Each replica sends heartbeats to the metadata PostgreSQL database
• Distributed coordination uses PostgreSQL advisory locks and row-level claiming
• Long-running tasks are owned by a replica; stale work is detected if that replica stops heartbeating
• Cancel signals are propagated across replicas through PostgreSQL NOTIFY/LISTEN

Kubernetes Example

The example below shows the minimum HA-specific changes compared with a single-replica deployment:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: bytebase
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: bytebase
  serviceName: bytebase
  template:
    metadata:
      labels:
        app: bytebase
    spec:
      containers:
        - name: bytebase
          image: bytebase/bytebase:latest
          env:
            # Replace the <> placeholders. See:
            # https://www.bytebase.com/docs/get-started/self-host/external-postgres
            - name: PG_URL
              value: "postgresql://<user>:<password>@<host>:<port>/<dbname>"
          args:
            - "--port"
            - "8080"
            - "--ha"
          ports:
            - containerPort: 8080

Use an ingress, gateway, or load balancer in front of the replicas so clients always access Bytebase through one stable URL.

Operational Notes

• HA is mainly for Kubernetes or other orchestrated environments. A single docker run deployment is still a single-node setup.
• Replicas do not require embedded PostgreSQL or shared local metadata storage.
• If multiple replicas are running without HA enabled in the license, Bytebase disables backend runners to avoid unsafe execution.
• Run administrator recovery beside the running replicas. Replicas started with --ha read users, settings, and policies from the metadata database on every request, so they apply a recovery change at once. Before 3.24.0, stop every replica first and restart all of them afterward.

Related Guides

• Production Setup
• Deploy with Kubernetes
• Configure External PostgreSQL
• Configure External URL