​
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:your_password@example.com: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:your_password@example.com: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.