Skip to main content
To add a PostgreSQL database, go to Instances, click Connect instance, and choose PostgreSQL.

​
Supported versions

Bytebase supports PostgreSQL 12 and later, including Amazon Aurora PostgreSQL and AlloyDB. It connects through a built-in driver, so there is nothing to install.

​
Create a user for Bytebase

Bytebase applies schema changes and reads the catalog of every database it manages, so give it a dedicated user with broad privileges instead of an application’s account. The examples name the user bytebase. On a self-managed server, connect as a superuser and run:
Managed services don’t give out SUPERUSER. Connect as the admin account the service gives you, create the user the same way, and grant the service’s admin role instead: These admin roles still can’t change objects that another role owns. To let Bytebase change them, grant it the owning role, such as GRANT app_owner TO bytebase;. For a read-only connection on PostgreSQL 14 or later, create a separate user:

​
Connection details

​
Authentication

How Bytebase signs in:
  • Plain Password: the Username and Password below.
  • AWS RDS IAM: an IAM authentication token for Amazon RDS or Aurora. See AWS.
  • Google Cloud SQL IAM: an IAM service account for Cloud SQL. See GCP.

​
Hostname

The host name or IP address of the PostgreSQL server, such as db.example.com. With Verify server certificate on, it must be one of the names in the server’s certificate.

​
Port

The server port. PostgreSQL’s default is 5432.

​
Username

The PostgreSQL role Bytebase connects as.

​
Password

The role’s password. You can also read it from a secret manager.

​
Connection database

The database Bytebase connects to when it isn’t working in a specific database, such as when it tests the connection or lists databases. If you leave it empty, Bytebase uses postgres. Set it when the role can’t connect to postgres. Bytebase lists every database on the server except template0 and template1 as a Bytebase database, whichever connection database you choose. Schemas such as public appear inside each one. See Database.

​
TLS

TLS mode decides whether Bytebase encrypts the connection:
  • Disabled: Bytebase adds no TLS settings, so the driver’s default applies. It uses TLS when the server offers it, without verifying the server, and connects unencrypted when the server doesn’t.
  • TLS: Bytebase always encrypts the connection, and fails if the server doesn’t offer TLS.
  • Mutual TLS: the same as TLS, and Bytebase also presents a client certificate, for servers that require one.
Under Server identity, turn on Verify server certificate so that Bytebase checks the server’s certificate and confirms that Hostname is one of the names in it. CA certificate source sets which certificate authority (CA) the check trusts:
  • System trust: the CAs that the machine running Bytebase already trusts.
  • Paste PEM: a CA certificate you paste in PEM format, for a private CA or a self-signed certificate.
  • File path: a CA certificate file on the Bytebase server. Not available in Bytebase Cloud.
With verification off, the connection is encrypted, but Bytebase doesn’t check which server it reached. Use that only for testing. For Mutual TLS, set Client identity source to Paste PEM or File path, and provide the client certificate and its private key.

​
SSH tunnel

Connects through a bastion host. See SSH Tunnel.

​
Extra Parameters

Connection parameters that Bytebase passes to the driver as key-value pairs, using libpq names such as connect_timeout. With TLS mode set to Disabled, sslmode controls encryption, so sslmode with the value disable keeps the connection unencrypted even when the server offers TLS.

​
Supabase

Bytebase connects to Supabase as a regular PostgreSQL server. To find the connection details, open your project in the Supabase dashboard and click Connect at the top of the page. Supabase offers three connection types: Copy the connection string for the type you chose. A session pooler string looks like this:
Fill in the form from it:
  • Hostname: the host from the string. Copy it rather than building it from your region, because the number after aws- varies.
  • Port: 5432.
  • Username: postgres for a direct connection, or postgres.<project_ref> for the session pooler.
  • Password: the database password you set when you created the project.
  • Connection database: leave it empty to use postgres.
To verify the server, download the CA certificate from Database settings > SSL Configuration with Download Certificate. Set TLS mode to TLS, turn on Verify server certificate, and paste the certificate with CA certificate source set to Paste PEM. System trust doesn’t work here, because Supabase signs its certificates with its own CA.

​
Neon

In the Neon Console, open your project and click Connect. In Connect to your branch, choose the branch, database, and role, then turn off Connection pooling to get the direct connection string. Neon recommends direct connections for schema migrations, and its pooler doesn’t keep session state between transactions.
Fill in the form from it:
  • Hostname: the host from the string, without -pooler in it.
  • Port: 5432.
  • Username: the role. Create it in the Neon Console so that it has neon_superuser.
  • Password: the role’s password.
  • Connection database: the database from the string, such as neondb.
Neon rejects unencrypted connections. Set TLS mode to TLS, turn on Verify server certificate, and keep CA certificate source at System trust. Neon’s certificates chain to Let’s Encrypt’s ISRG Root X1, which the system already trusts.

​
Troubleshooting

Test Connection shows the error from the server or the driver:

​
Read-only connection

A read-only connection has its own TLS settings and Extra Parameters. Set them the same way as for the admin connection.