Configure External PostgreSQL

PostgreSQL Setup

PostgreSQL 14 or above.

Database

Create a database named bytebase with UTF-8 encoding. UTF-8 encoding is required for proper system operation.

User

Create a user bytebase with one of the following privilege levels:

Option 1: Superuser

This option is not available on managed database services like AWS RDS or Google Cloud SQL.

Grant PostgreSQL superuser privileges:

ALTER ROLE bytebase SUPERUSER;

Option 2: Database Owner

Make the user own the database:

ALTER DATABASE bytebase OWNER TO bytebase;

Option 3: Schema Create Privilege

Grant CREATE privilege on the public schema:

GRANT CREATE ON SCHEMA public TO bytebase;

Option 4: Database Owner Role

Grant the db_owner role to the user:

GRANT db_owner TO bytebase;

PG_URL Environment Variable

The PG_URL environment variable configures the PostgreSQL connection for Bytebase. You can set it in two ways:

Direct Connection String

Set PG_URL directly to a PostgreSQL connection URI:

PG_URL="postgresql://bytebase:[e-mail]:5432/bytebase"

File Path (Kubernetes & Secret Management)

For Kubernetes deployments and secret manager integration, set PG_URL to a file path containing the connection string. Bytebase automatically picks up the updated connection string when the file content changes, enabling seamless secret rotation.

PG_URL="/path/to/connection/file"

The connection string must follow the standard PostgreSQL URI format. See the official PostgreSQL documentation for complete syntax details.

Example:

postgresql://bytebase:[e-mail]:5432/bytebase

Running with Docker

This bash script demonstrates how to add an external PostgreSQL database as the metadata store when running the bytebase container.

When connecting to a PostgreSQL instance running on the same host machine, use host.docker.internal as the hostname.

docker run --rm --init \
  -e PG_URL=postgresql://user:secret@host:port/dbname \
  --name bytebase \
  --publish 8080:8080 --pull always \
  --volume ~/.bytebase/data:/var/opt/bytebase \
  bytebase/bytebase:latest

Running with Kubernetes

Direct Configuration

Configure the PostgreSQL connection directly in your deployment manifest:

env:
  - name: PG_URL
    value: 'postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<dbname>>'

Secret-Based Configuration

For enhanced security, store your PostgreSQL connection string in a Kubernetes Secret:

Using Secret as Environment Variable

Add the following environment variable configuration to your deployment’s spec.templates.spec.containers.env section:

env:
  - name: PG_URL
    valueFrom:
      secretKeyRef:
        name: secret_name
        key: secret_key

Using Secret as File Mount

Mount the secret as a file and point PG_URL to the file path. This approach supports automatic secret rotation - when the Kubernetes Secret is updated, the mounted file content is automatically refreshed, and Bytebase will pick up the new connection string without requiring a restart:

spec:
  containers:
    - name: bytebase
      env:
        - name: PG_URL
          value: "/var/secrets/pg-connection/url"
      volumeMounts:
        - name: pg-secret
          mountPath: "/var/secrets/pg-connection"
          readOnly: true
  volumes:
    - name: pg-secret
      secret:
        secretName: bytebase-pg-secret
        items:
          - key: connection-string
            path: url

When using file-based secrets, Kubernetes automatically updates the mounted file content when the Secret is updated (typically within a minute). Bytebase monitors the file for changes and automatically reloads the connection string, enabling seamless secret rotation without downtime.