Skip to main content

​
Connecting to your PlanetScale Postgres database

Connecting to your PlanetScale Postgres database involves understanding several key components. This page provides an overview of connection options — for detailed instructions, see the linked documentation below.

​
Roles and credentials

PlanetScale provides two types of roles for database access:
  • Default postgres role — A near-superuser role with extensive permissions, ideal for administrative tasks and initial database setup. This role should not be used for application connections.
  • User-defined roles — Custom roles with specific permission sets that follow the principle of least privilege. These are recommended for all application connections and allow credential rotation without downtime.
Connection credentials include a hostname, username (formatted as {role}.{branch_id}), password (prefixed with pscale_pw_), and database name. Learn more about managing roles and creating credentials.

​
Connection strings

PlanetScale databases require SSL/TLS encryption for all connections. Connection strings include parameters for the host, port, username, password, database name, and SSL configuration. The port determines the connection method:
  • Port 5432 — Direct connections to Postgres, bypassing PgBouncer
  • Port 6432 — Connections through PgBouncer for connection pooling
The connections quickstart provides detailed connection string examples and explains when to use each connection method.

​
Private connectivity

For enhanced security and reduced latency, PlanetScale supports private connectivity that keeps traffic within cloud provider networks:
  • AWS PrivateLink — Establishes private connections from your AWS VPC to PlanetScale databases without exposing traffic to the public internet. See the AWS PrivateLink documentation.
  • GCP Private Service Connect — Provides private connectivity from your Google Cloud VPC to PlanetScale databases. See the GCP Private Service Connect documentation.

​
Neon Serverless Driver

For serverless and edge environments, PlanetScale supports connections via the Neon serverless driver. This driver is optimized for platforms like Vercel Functions, AWS Lambda, and edge runtimes like Cloudflare Workers. Both HTTP and WebSocket modes are supported, HTTP mode for simple one-shot queries, and WebSocket mode for transactions and session-based features.

​
Understanding Postgres connections

Postgres uses a connection-per-process architecture. Each connection made to a Postgres server spawns a new process, which consumes system resources including memory and CPU. For this reason, it’s important to manage the number of direct connections to keep the system performant. Connection pooling is the primary solution to this challenge. In the Postgres ecosystem, PgBouncer is the most widely-used connection pooler. PgBouncer instances sit between clients and the Postgres server, maintaining a small pool of connections to Postgres while accepting a much larger number of client connections. PgBouncer routes client requests through these pooled connections efficiently.

​
Connection options

PlanetScale provides several ways to connect to your Postgres database:
  1. Direct primary connections - Connect directly to your Postgres primary server on port 5432. This provides the lowest latency and full Postgres session capabilities. Use this for administrative tasks, long-running operations, and data imports.
  2. Direct replica connections - Connect directly to read-only replicas on port 5432 by appending |replica to your username. Use this for read-only queries that can tolerate replication lag.
  3. Local PgBouncer (primary only) - All Postgres databases include a local PgBouncer running on the same host as the primary. Connect via port 6432. This is recommended for all application connections to the primary.
  4. Dedicated replica PgBouncer - Create dedicated PgBouncer instances that pool connections to your replicas. These run on separate nodes and are useful for read-heavy workloads. Connect via port 6432 with the PgBouncer name appended to your username.
  5. Dedicated primary PgBouncer - Create dedicated PgBouncer instances that pool connections to your primary database. These run on separate nodes and provide improved high availability, with connections persisting through cluster resizes, upgrades, and most failover scenarios. Connect via port 6432 with the PgBouncer name appended to your username.
The following sections describe each option in detail to help you choose the right connection method for your use case.

​
Direct primary connections

Direct connections provide the lowest-latency access to your Postgres primary instance.
Direct connections
However, these connections are considered heavy-weight since each one consumes significant resources. Direct connections are recommended only for specific scenarios:
  1. Administrative tasks, like creating new databases/schemas, manual DDL commands, and installing extensions.
  2. Long-running operations like VACUUMs and large analytical queries that are executed infrequently.
  3. Importing data during a migration or other bulk-loading operations.
  4. When you need features like SET, pub/sub, and other features not provided by PgBouncer pooled connections.
Because having too many direct connections degrades performance, PlanetScale sets max_connections to a conservative default value that varies depending on cluster size. To find this value, navigate to the “Clusters” page and select the “Parameters” tab. Navigate to the Cluster Parameters page Search for max_connections to view the current configured value. This can be increased if necessary, though doing so requires careful consideration as increasing direct connections can negatively impact performance. When the max_connections limit is reached, error messages like the following will appear: 
FATAL: sorry, too many clients already
Or variations such as: 
FATAL: remaining connection slots are reserved for non-replication superuser connections
For application connections outside of the specific use cases listed above, PgBouncer should be used instead.

​
Direct replica connections

The main purpose for the default Replicas in a cluster is to maintain high-availability, but they can also be used to handle read traffic. Since replicas are read-only, they are only capable of serving SELECT queries. All write traffic (INSERT, UPDATE, etc) must be sent to the primary.
Direct replica connections
Replicas always experience some level of replication lag — the delay between data arriving at the primary and being replicated to a replica. Frequently, replication lag is measured in milliseconds, but it can grow to multiple seconds, especially when the server is experiencing high write traffic or network issues. Because of these factors, queries should only be sent to replicas if they meet the following criteria: (A) they are read-only and (B) they can tolerate being slightly out-of-sync with the data on the primary. For reads that cannot tolerate this lag, send them to the primary. To connect to a replica, append |replica to your credential username and use port 5432. For example: 
psql 'host=xxxxxxxxxx-useast1-1.horizon.psdb.cloud \
      port=5432 \
      user=postgres.xxxxxxxxxx|replica \
      password=pscale_pw_xxxxxxxxxxxxxxxxxx \
      dbname=my_database \
      sslnegotiation=direct \
      sslmode=verify-full \
      sslrootcert=system'
Learn more about replicas and when to use them in the database replicas documentation.

​
PgBouncer connections

PgBouncer provides connection pooling for your Postgres database, allowing applications to scale beyond the constraints of direct connections. Connections from application servers should be made via PgBouncer whenever possible. PlanetScale provides three types of PgBouncer instances:

​
Local PgBouncer

Local PgBouncer connections
All PlanetScale Postgres databases include a local PgBouncer instance running on the same host node as the Postgres primary. This is recommended for all application connections to the primary. To connect via the local PgBouncer, use the same credentials as a direct connection but change the port from 5432 to 6432.
The local PgBouncer only routes connections to the primary. To pool connections to replicas, use a dedicated replica PgBouncer.

​
Dedicated replica PgBouncer

Dedicated replica PgBouncer connections
Dedicated replica PgBouncers run on nodes separate from the Postgres instances and pool connections to your replicas. These are useful for read-heavy workloads that send significant read traffic to replicas.

​
Dedicated primary PgBouncers

Dedicated primary PgBouncer connections
Dedicated primary PgBouncers provide connection pooling for your primary database on nodes separate from the Postgres servers. Connections through dedicated PgBouncers persist through cluster resizes, upgrades, and most failover scenarios, providing improved high availability.

​
Connecting to dedicated PgBouncers

Connect to replica or primary PgBouncers via port 6432 and append the name of the PgBouncer to your username. For example, if your PgBouncer is named read-bouncer, the connection username should be postgres.xxxxxxxxxx|read-bouncer. 
psql 'host=xxxxxxxxxx-useast1-1.horizon.psdb.cloud \
      port=6432 \
      user=postgres.xxxxxxxxxx|read-bouncer \
      password=pscale_pw_xxxxxxxxxxxxxxxxxx \
      dbname=my_database \
      sslnegotiation=direct \
      sslmode=verify-full \
      sslrootcert=system'
Learn more about creating, configuring, and connecting to PgBouncers.