Skip to content

docs: improve external PostgreSQL configuration documentation #811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
d-bytebase merged 2 commits into from
Aug 12, 2025
Merged

docs: improve external PostgreSQL configuration documentation #811

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ad0a5b3
docs: remove troubleshooting section from external PostgreSQL configu…
d-bytebase Aug 12, 2025
b8c6b5a
docs: improve external PostgreSQL configuration documentation
d-bytebase Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 11 additions & 24 deletions mintlify/get-started/self-host/external-postgres.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,24 +4,10 @@ title: Configure External PostgreSQL

import TerminalDockerRunPgUrl from '/snippets/install/terminal-docker-run-pg-url.mdx';

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 Setup

PostgreSQL 14 or above.

## Connection string format for PG_URL

**Supported format:**

_postgresql://\<\<user>>:\<\<secret>>@\<\<host>>:\<\<port>>/\<\<database>\>_

**Example:**

_postgresql://bytebase:z\*[email protected]: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**.
Expand Down Expand Up @@ -52,17 +38,23 @@ The connecting `user` must have all the following database privileges:
- EXECUTE
- USAGE

### Host
### PG_URL String Format

**Supported format:**

_postgresql://\<\<user>>:\<\<secret>>@\<\<host>>:\<\<port>>/\<\<database>\>_

**Example:**

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`.
_postgresql://bytebase:z\*[email protected]:5432/meta_

## Docker example
## Running with Docker

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

<TerminalDockerRunPgUrl />

## Kubernetes Configuration
## Running with Kubernetes

### Using Connection String in YAML

Expand Down Expand Up @@ -95,8 +87,3 @@ env:

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](https://artifacthub.io/packages/helm/bytebase/bytebase).

## 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](#user) and [GitHub Issue](https://github.com/bytebase/bytebase/discussions/14041).