Last updated May 18, 2026

Heroku Postgres Advanced enforces connection limits per compute instance. This article explains how connection limits work across compute instances and instance pools, how connections distribute across pool endpoints, and how to monitor connection usage.

Connection Limits Per Compute Instance

Each compute instance in your database cluster has a fixed connection limit based on its compute level. These limits apply per compute instance, not per cluster or per instance pool. The maximum connection limit for any single compute instance is 5,000. Compute levels at 64G-Performance and higher share this cap.

Instance Pool Connection Limits

The total connection limit for an instance pool depends on whether it’s a leader pool or a follower pool and the number of compute instances in the instance pool. See Managing Instance Pools on Heroku Postgres Advanced for more information on Postgres Advanced instance pools.

Leader Instance Pool

The leader instance pool has a connection limit equal to a single compute instance’s limit. Only the leader compute instance accepts connections. The standby compute instance doesn’t serve client connections and doesn’t add to the instance pool’s connection limit.

For example, a leader pool with a 128G-Performance compute level and high availability enabled has a connection limit of 5,000.

Follower Instance Pools

Follower instance pools have a connection limit equal to the per-instance limit multiplied by the number of compute instances in the pool. You can increase your connection limit by adding more compute instances to a follower pool.

For example, a follower pool with two 4G-Performance compute instances has a total connection limit of 760 (380 × 2).

Removing a compute instance decreases the total connection limit on the instance pool. We recommend maintaining a buffer of available connections to avoid connection errors, especially when downgrading the compute level or reducing the number of compute instances.

Connections Distribution on Instance Pool Endpoints

Each instance pool has an endpoint that your app uses to connect. Understanding how these endpoints distribute connections helps with capacity planning.

DNS Round-Robin Distribution

Instance pool endpoints distribute connections using DNS round-robin with a 5-second time-to-live (TTL). When your app resolves the endpoint hostname, DNS returns the IP address of one compute instance in the instance pool. Each DNS resolution can return a different compute instance.

This method is passive distribution, not active load balancing. The endpoint doesn’t track how many connections each compute instance has or route new connections to the least-loaded instance. Instead, it rotates through compute instance IP addresses via DNS.

Considerations

Because distribution relies on DNS round-robin, it doesn’t guarantee distributing connections evenly across compute instances. Several factors can cause an imbalanced distribution:

• DNS caching: If your app or connection pool library caches DNS results beyond the 5-second TTL, many connections can land on the same compute instance. Ensure your app respects DNS TTL values.
• Client-side connection pool startup: When a client-side connection pool opens many connections at once, they can all resolve to the same compute instance if opened before the DNS TTL rotates.
• Long-lived connections: Connections that remain open for extended periods stay on the compute instance they originally connected to, regardless of subsequent DNS changes.

Example

Consider a follower instance pool with three compute instances at 16G-Performance (1,600 connections each, 4,800 total):

• Best case: Connections distribute roughly evenly with approximately 1,600 connections per compute instance.
• Worst case: DNS caching or client-side connection pool behavior concentrates connections on one compute instance. This scenario can potentially exceed its 1,600 connection limit while other compute instances sit idle.

Even though the instance pool has a total capacity of 4,800 connections, any single compute instance can only accept 1,600 connections. If an imbalanced distribution sends more than 1,600 connections to one compute instance, the compute instance refuses the the excess connections.

Monitoring Connection Usage

Heroku Postgres Advanced emits metrics to your app’s log stream that include connection counts at the instance pool level. You can view these logs using the Heroku CLI:

$ heroku logs -d heroku-postgres --app example-app

You can also view connections and connection limits from the CLI with data:pg:info and the Heroku Dashboard.

Instance Pool Connection Metrics

Instance pool logs are tagged with [instance-pool] and include the following connection metrics:

Example log line:

app[heroku-postgres]: [instance-pool] addon=postgresql-example-12345 instance-pool=analytics sample#active-connections=0 sample#max-connections=1200 sample#connections-percentage-used=0.00000 sample#load-avg-1=(...)

For more information on all available Heroku Postgres metrics, see Heroku Postgres Metrics Logs.