High Availability

​

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

​

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

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

​

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.
• Upgrade replicas one version at a time, and read the release’s changelog for upgrade notes before you start. Some releases can’t be upgraded one replica at a time and need every replica stopped first.
• 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