Connecting to your PlanetScale for Postgres database

July 1, 2025

PlanetScale for Postgres will work with any PostgreSQL driver or library that supports SSL connections. This documentation covers:

Creating a password

Every PostgreSQL database comes with a default postgres role that you can generate upon creating your database. This is the only role that can be managed from your PlanetScale dashboard. It has the most privileged access to your database and can be used to create additional roles with less permissions. See the postgres role section for more information.

1. From the PlanetScale organization dashboard, select the desired database
2. Select the desired branch from the dropdown
3. Click "Connect"
4. Click "Create default role"
5. This generates the unique username and password pair for your default user that you can use to access the designated branch of your database.

You'll be provided with the following:

DATABASE_HOST=**********-<REGION>.horizon.psdb.cloud
DATABASE_NAME=<DATABASE_NAME>
DATABASE_USERNAME=postgres.<BRANCH_ID>
DATABASE_PASSWORD=pscale_pw_**************************

Here is an example of the connection string that connects directly (without PSBouncer) you can use to connect to the Postgres CLI:

psql 'host=xxxxxxxxxx-useast1-1.horizon.psdb.cloud \
      port=5432 \
      user=postgres.xxxxxxxxxx \
      password=pscale_pw_xxxxxxxxxxxxxxxxxx \
      dbname=my_database \
      sslnegotiation=direct \
      sslmode=verify-full \
      sslrootcert=system'

Connection parameters

Secure connections

All PlanetScale for Postgres connections require SSL/TLS encryption. The following parameters are used to enforce this:

Managing roles

Once you've generated credentials for this default role, you can use these credentials to generate additional users and roles as needed. You cannot manage these additional users and roles from within the PlanetScale dashboard.

We do not recommend connecting to your application using the default role, as you will need to take some downtime if you ever have to rotate your password.

Connecting to non-default roles

PlanetScale's routing layer uses the user to identify which database or branch we are sending queries to. For example, the user matt.nk35mx55qq routes to the PlanetScale database with branch id nk35mx55qq. When you're creating the new role, you do not need to specify the branch id on the user. You can simply set the user to matt.

However, when you connect, you must append the branch id to the user so we know which branch to route to.

1. From the PlanetScale organization dashboard, select the desired database
2. Select the desired branch from the dropdown
3. Click "Connect"
4. Copy the branch id
5. Append it to your user with .branch_id

Resetting the default password

If you need to reset the password for the default postgres role:

1. From the PlanetScale organization dashboard, select the desired database
2. Select the desired branch from the dropdown
3. Click "Connect"
4. Click "Reset default role"
5. Update the credentials any place that they are in use

Default postgres role

The default postgres role is the only role you can manage within the PlanetScale dashboard. It is similar to the Postgres superuser, but with fewer permissions. It is defined by the following statement:

CREATE ROLE $POSTGRES_USERNAME
  NOSUPERUSER CREATEDB CREATEROLE INHERIT LOGIN REPLICATION BYPASSRLS PASSWORD

It also inherits the following permissions:

GRANT pg_read_all_data,
  pg_write_all_data,
  pg_read_all_settings,
  pg_read_all_stats,
  pg_stat_scan_tables,
  pg_monitor,
  pg_signal_backend,
  pg_checkpoint,
  pg_maintain,
  pg_use_reserved_connections,
  pg_create_subscription
TO $ALMOST_SUPERUSER_ROLENAME WITH ADMIN OPTION;

We do not recommend connecting to your application using the default role, as you will need to take some downtime if you ever have to rotate your password. Instead, you should generate additional roles as needed.

Connection types: Direct vs PSBouncer

PlanetScale offers two connection methods for PostgreSQL databases: direct (port 5432) and via PSBouncer (port 6432).

Direct connection (Port 5432)

Using port 5432 bypasses PSBouncer and connects directly to Postgres. This is the recommended way to connect for any operations that require long-running queries or persistent connections.

PSBouncer operates in transaction pooling mode, where connections are returned to the pool after each transaction completes. This means that session-level features and long-running operations are interrupted between transactions.

Direct connections are recommended for:

• Schema changes and DDL
• OLAP, analytics, reporting, or batch processing
• Session-specific features: Custom session variables, temporary tables
• ETL processes and data streaming
• Long-running transactions or queries that span multiple transactions

Additionally, if you're connecting to a replica, you must connect directly. PSBouncer is not supported for replica connections.

PSBouncer connection (Port 6432)

PSBouncer enables high availability for a Postgres database by efficiently pooling connections and buffering queries during failovers. PSBouncer is generally recommended for OLTP workloads. For example, we'd recommend routing your application connections through PSBouncer. You can connect through PSBouncer by updating your connection string to use port 6432.

PSBouncer connections operate in transaction mode, which means each connection is only held for the duration of a single transaction. This provides excellent performance for OLTP workloads but limits certain PostgreSQL features that require persistent connections. For use cases that require long-running operations, we recommend a direct connection on port 5432.

Routing to replicas

PlanetScale for Postgres supports routing connections to replicas for improved read performance and load distribution. To connect to a replica, append |replica to your credential username. For example:

# Connect to replica
user=postgres.xxxxxxxxx|replica # where postgres.xxxxxxxxx is your username

You can append |replica to any role you create on your Postgres database.

Authentication

PlanetScale for Postgres uses SCRAM-SHA-256 authentication, which provides enhanced security over traditional password authentication methods.

Username format

All usernames follow the format {role}.{branch_id}:

The branch ID in the username tells PlanetScale's routing layer (Exosphere) which specific database branch to connect to.

Password format

All PlanetScale for PostgreSQL passwords begin with pscale_pw_ followed by a unique string:

pscale_pw_OdDz7oyyxZWcXE5bO9h5pFBghz0J3E3Q

Strong security model

PlanetScale roles are created for use with a single database branch. This strong security model allows you to generate roles that are tied to a branch, and cannot access data/schema from another branch.

Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.