Log in|Book a meeting
Navigation

PgBouncer

Postgres

PlanetScale uses PgBouncer to enable high availability for Postgres databases by efficiently pooling connections and buffering queries during failovers.

When to use PgBouncer

PgBouncer is generally recommended for OLTP workloads. For example, we'd recommend routing your application connections through PgBouncer. You can connect through PgBouncer by updating your connection string to use port 6432.

PgBouncer 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.

Connecting through PgBouncer

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

To connect to PgBouncer, switch the port in your connection string from 5432 to 6432. For example:

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

Note

PlanetScale's use of PgBouncer (port 6432) does not support replica routing. All connections through PgBouncer are automatically routed to the primary database, regardless of the username specification. Use direct connections (port 5432) for replica access.

PgBouncer configuration

Your cluster's PgBouncer settings are automatically configured based on your cluster size, but you can customize pooling parameters on your database's cluster configuration page under Parameters:

  • Number of processes: Number of PgBouncer processes per node (1-4)
  • Default pool size: Default connection pool size
  • Max client connections: Maximum client connections
  • Max prepared statements: Maximum prepared statements cache
  • Server lifetime: Connection lifetime settings
  • Server idle timeout: Idle connection timeout

These settings are managed through your cluster parameters and don't require changes to your application connection strings.

Need help?

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