By default, Bytebase bundles an embedded PostgreSQL instance for storing its own metadata. The metadata is stored under the --data directory. For production setup, you should pass PG_URL environment variable to store these metadata in an external PostgreSQL database.

​
Postgres version

PostgreSQL 14 or above.

​
Connection string format for PG_URL

Supported format: postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<database>> Example: postgresql://bytebase:z*3kd2@example.com:5432/meta

​
Database

The connecting database must be created in advance. The database should use UTF-8 for encoding. UTF-8 encoding is mandatory across the entire system.

​
User

For Cloud Database such as AWS RDS, GCP Cloud SQL, ensure that the user either owns the schema (public) and database, or has the necessary privileges to access them.
  • ALTER DATABASE database OWNER TO bytebase;
  • ALTER SCHEMA public OWNER TO bytebase;
The connecting user must have all the following database privileges:
  • SELECT
  • INSERT
  • UPDATE
  • DELETE
  • TRUNCATE
  • REFERENCES
  • TRIGGER
  • CREATE
  • CONNECT
  • TEMPORARY
  • EXECUTE
  • USAGE

​
Host

If you run Bytebase inside Docker and want to connect the pg instance on the same host, then you need to use host.docker.internal.

​
Docker example

This bash script demonstrates how to add an external PostgreSQL database as the metadata store when running the bytebase container.
Use host.docker.internal as the host if you connect the pg instance on the same host.
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

​
Kubernetes Configuration

​
Using Connection String in YAML

You can specify the PostgreSQL connection string directly in your Kubernetes YAML file: 
env:
  - name: PG_URL
    value: 'postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<dbname>>'

​
Using Kubernetes Secrets

Instead of specifying PostgreSQL connection string directly in Helm or Kubernetes yaml file, you can use Kubernetes secrets resources:

​
Kubernetes

Use the following yaml section to replace the spec.templates.spec.containers.env section: 
env:
  - name: PG_URL
    valueFrom:
      secretKeyRef:
        name: secret_name
        key: secret_key

​
Helm

Use --set bytebase.option.existingPgURLSecret and --set bytebase.option.existingPgURLSecretKey to specify the secret key and secret name instead of --set "bytebase.option.external-url"={NEW_EXTERNAL_URL}. See more details in Bytebase - Artifact Hub.

​
Troubleshoot

​
Cannot new server ERROR: syntax error at or near xxx

Make sure that the connecting user is either superuser or is the owner of the connecting database. See User and GitHub Issue.