Connection Pooling for Render Postgres

Render Postgres now supports integrated connection pooling with PgBouncer.

Previously, this guide described manually configuring and deploying PgBouncer as a standalone Render service. It has been updated to use integrated connection pooling.

If your Render Postgres database requires more simultaneous connections than its compute plan allows, you can enable connection pooling for it at no additional cost. When enabled, Render runs PgBouncer in front of your database to manage its connection volume:

With this setup, you update your clients to connect to PgBouncer instead of connecting directly to your database. PgBouncer maintains a pool of reusable connections to handle queries from thousands of clients.

PgBouncer runs on the same underlying host as the database itself, minimizing the latency introduced by this additional hop. Clients that require session-level state or a dedicated long-lived connection can continue connecting directly.

Connection pooling is not available for free databases.

Should I enable connection pooling?

It depends. A connection pool is most commonly useful in the following cases:

Your database's connection limit is too low for your number of concurrent clients.
Your database consistently receives surges of short-lived connections from bursty workloads (such as from Render Workflows).
- In this case, pooling helps minimize connection management overhead on your database.

Outside of these cases, most databases don't benefit meaningfully from a connection pool.

If you do enable connection pooling, some clients might still need to connect directly to your database.

When to connect directly

Render-managed PgBouncer uses transaction-level pooling (pool_mode = transaction). This means that clients requiring session-level state or a dedicated long-lived connection should continue connecting directly to your database.

Connect directly if your client uses any of the following:

Custom session variables (SET SESSION …)
Temporary tables (CREATE TEMPORARY TABLE …)
LISTEN/NOTIFY
Session-level advisory locks

If a significant percentage of your clients require the above features, do not enable connection pooling.

Setup

1. Enable connection pooling

This step requires a database restart, unless you've enabled high availability.

During a restart, your database is unavailable for a few minutes.
If you've enabled high availability, your database instead is unavailable for a few seconds (during the failover process).

Schedule activation of this feature accordingly.

Enable connection pooling for your database using any method listed below:

In the Render Dashboard, go to your database's Info page and scroll down to General > Connection Pool:
Toggle the switch.

A confirmation modal appears:
Confirm your action and click Enable connection pool.

Render immediately triggers a database restart or HA failover to initialize the connection pool.

Enable connection pooling using the Render CLI's pg update command. Set the --connection-pool flag to pgbouncer:

Render immediately triggers a database restart or HA failover to initialize the connection pool.

Using the Render API, enable connection pooling with a request to the Update Postgres instance endpoint.

In your request body, set connectionPool to pgbouncer:

Render immediately triggers a database restart or HA failover to initialize the connection pool.

Existing clients are not yet using the connection pool! You'll update them next.

2. Update your client connections

After your database finishes restarting, it has two new connection pool URLs, one for internal connections and one for external connections. You can view these URLs on your database's Info page in the Render Dashboard:

Copying a connection pool URL in the Render Dashboard

These URLs are almost identical to your database's direct connection URLs, with one difference: they use the PgBouncer port 6432 instead of defaulting to the standard PostgreSQL port 5432.

Update each of your clients with the relevant URL for its connection type. For your other Render services, this almost always involves updating an environment variable. See the most common update methods:

In the Render Dashboard, go to your service's Environment page and scroll down to Environment Variables.
Click Edit.
Find the environment variable containing your database's connection URL (most commonly DATABASE_URL).
Update the value of the environment variable to the new connection pool URL.
- Make sure to use the connection URL that corresponds to the existing connection type (internal / external).
Click the dropdown arrow next to Save only and select Save and deploy.

Render redeploys your service with the updated environment variable.

Using the Render API, update the environment variable your client uses for database connections with the Add or update environment variable endpoint.

In your request body, set value to the new connection URL:

Default configuration

Render uses the following default configuration for PgBouncer:

Does your use case require custom PgBouncer configuration?

Please reach out to our support team in the Render Dashboard.

Setting	Value	Details
`pool_mode`	`transaction`	Because connections are assigned per-transaction, session-level features like advisory locks and `LISTEN/NOTIFY` require connecting directly.
`max_client_conn`	`30000`	This is the maximum number of simultaneous connections PgBouncer accepts from clients, not the number of connections it maintains to your database.
`max_db_connections` / `default_pool_size`	`max_connections` minus 10	Render Postgres reserves 10 connections for direct database connections and internal operations.
`client_idle_timeout`	`86400` (1 day in seconds).	PgBouncer closes idle client connections after this duration.
`server_login_retry`	`2` (seconds)	If PgBouncer fails to connect to your database, it waits this long before retrying.
PgBouncer port	`6432`	Direct database connections continue to use port `5432`. Only connections through PgBouncer use this port.

Monitoring pool activity

If your workspace streams metrics to an observability provider, Render reports render.postgres.connection.pool.* metrics for each database with connection pooling enabled. Use these metrics to detect pool saturation: for example, render.postgres.connection.pool.client.waiting reports the number of clients waiting for an available connection.

For the full list of reported metrics, see the Render OpenTelemetry Metrics Reference.

FAQ

Can I enable connection pooling for a free database?

No. Connection pooling requires a paid compute plan.

Can I enable connection pooling for my database's read replicas?

If you enable connection pooling for a primary database, Render automatically enables it for all of that database's read replicas.

Each read replica has its own independent connection pool. You can't toggle connection pooling for a replica independently of its primary.

How does connection pooling work with high availability?

If you enable connection pooling for a primary database, Render automatically enables it for that database's high availability standby (if it has one).

In the event of a failover, the standby becomes the new primary, and clients start using its connection pool immediately upon reconnecting.

If I enable connection pooling, are all my database's clients required to use it?

No. Render Postgres reserves a small number of connections for direct database connections and internal operations. Clients with specific requirements can continue connecting directly using the database's internal or external URL.

If a significant percentage of your clients require a direct connection, do not enable connection pooling.

Can I customize my database's PgBouncer configuration?

Not directly. If your use case requires custom PgBouncer configuration, please reach out to our support team in the Render Dashboard.