Configure External PostgreSQL

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 supply --pg or pass PG_URL environment variable to store these metadata in an external PostgreSQL database.


  1. PostgreSQL 14 or above.
  2. All privileges on the database object including:
    • SELECT
    • INSERT
    • UPDATE
    • DELETE
    • CREATE
    • USAGE
  3. The database should use UTF-8 for encoding. UTF-8 encoding is mandatory across the entire system.
  4. For Cloud RDS, ensure that the user either owns the schema (public) and database, or has the necessary privileges to access them.
    • ALTER DATABASE dbname OWNER TO bytebase;
    • ALTER SCHEMA public OWNER TO bytebase;

--pg connection string

Alternatively, you can also pass PG_URL environment variable.

Supported format:

  • postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<dbname>>

  • postgresql://<<user>>:<<secret>>@<<host>>:<<port>>/<<dbname>>?sslrootcert=<<root.pem>>



  • user must be specified.
  • dbname must be specified and must be created in advance. The connecting user must have all the database privileges mentioned above.
  • host. If you run Bytebase inside Docker and want to connect the pg intance on the same host, then you need to use host.docker.internal.
Edit this page on GitHub

Subscribe to Newsletter

By subscribing, you agree with Bytebase's Terms of Service and Privacy Policy.