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.
You can expose read-only schema and query capabilities to tools like Claude, Cursor, or Zed through the shared Model Context Protocol (MCP) guide. The CLI configures each tool for you via pscale mcp install --target <claude|cursor|zed>, and the PlanetScale MCP server streams data over a secure, read-only connection.
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.
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.
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.
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.
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.
PlanetScale provides several ways to connect to your Postgres database:
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.
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.
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.
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.
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.
