If your application creates many short-lived connections or generates high connection churn, enabling the connection pool (PgBouncer) reduces database server load and improves response time. PgBouncer sits between your application and ApsaraDB RDS for PostgreSQL, reusing backend connections across many client connections so the database avoids repeatedly opening and closing them.
When to use connection pooling
Not every workload benefits from PgBouncer. Use this table to decide whether to use a pooled or direct connection.
| Scenario | Connection type | Why |
|---|---|---|
| Serverless or edge functions | Pooled | Each invocation creates a new connection |
| Web applications with many concurrent requests | Pooled | Reduces per-request connection overhead |
| High connection churn from ORM frameworks | Pooled | Reuses backend connections |
| Schema migrations | Direct | Migration tools may use SET statements or advisory locks |
| Long-running analytics queries | Direct | Avoids pool contention |
pg_dump or pg_restore | Direct | Uses session-level SET statements |
| Logical replication | Direct | Requires a persistent session |
| Prepared statements (in transaction mode) | Direct | Not supported in transaction pooling |
Prerequisites
Before you begin, make sure your ApsaraDB RDS for PostgreSQL instance meets all of the following requirements:
Major engine version: PostgreSQL 11 or later
Product series: Basic Edition or High-availability Edition
Billing method: subscription or pay-as-you-go
Minor engine version: 20240830 or later, without the
babelfishsuffix
To view or upgrade the minor engine version, see Upgrade the minor engine version of an ApsaraDB RDS for PostgreSQL instance.
Billing
This feature is free of charge.
How it works
PgBouncer acts as middleware between your application and the database. Clients connect to PgBouncer on port 6432 (default). PgBouncer maintains a pool of backend connections to PostgreSQL on port 5432 (default) and assigns them to clients according to the configured pool mode.
When PgBouncer is enabled:
A new PgBouncer port (default: 6432) is allocated. Your existing connections through the original database port (5432) are not affected.
The system installs the
pgbouncer_fdwanddblinkplugins in thepostgresdatabase to support connection pool metrics. These plugins cannot be uninstalled.
Enable or disable the connection pool
Go to the Instances page. In the top navigation bar, select the region where your RDS instance resides. Find the instance and click its ID.
In the left navigation pane, click Database Connection.
Click Enable PgBouncer or Disable PgBouncer.
In the dialog box that appears, click OK.
After PgBouncer is enabled, the PgBouncer port (default: 6432) appears on the Database Connection page. To change the port, click Modify Endpoint, select an endpoint type, and update the PgBouncer Port field.
Connect through the connection pool
After enabling PgBouncer, update your application's connection port from 5432 to 6432. All other connection parameters — endpoint, username, and password — remain unchanged.
Before (direct connection):
postgresql://<username>:<password>@<endpoint>:5432/<database>After (pooled connection):
postgresql://<username>:<password>@<endpoint>:6432/<database>For more information, see Connect to an ApsaraDB RDS for PostgreSQL instance.
Configure connection pool parameters
After enabling PgBouncer, use the Parameter Settings feature to adjust connection pool behavior.
The default parameter template is PostgreSQL_PgBouncer_Default Parameter Template (rpg-sys-pgsql-pgbouncer).
Pool mode
The pgbouncer.pool_mode parameter controls when PgBouncer returns a backend connection to the pool.
| Mode | Default | How it works | When to use |
|---|---|---|---|
transaction | Yes | Returns the connection after each transaction | Most applications. Provides the highest connection reuse. |
session | No | Returns the connection when the client disconnects | Applications that use session-level features (SET, LISTEN, prepared statements, advisory locks) |
statement | No | Returns the connection after each statement. Autocommit workloads only. Transactions spanning multiple statements are not supported. | Autocommit-only workloads |
Connection limits
The following parameters control how many connections PgBouncer accepts and forwards to the database. max_client_conn and default_pool_size operate at different layers: max_client_conn caps incoming client connections, while default_pool_size caps outgoing backend connections. Many clients can share a smaller pool of backend connections — that is the core benefit of connection pooling.
| Parameter | Type | Default | What it controls |
|---|---|---|---|
pgbouncer.max_client_conn | int | 100 | Maximum number of client connections PgBouncer accepts |
pgbouncer.default_pool_size | int | 20 | The default number of connections allowed in the connection pool |
pgbouncer.min_pool_size | int | 0 | The minimum number of client connections allowed by the connection pool |
Other parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
pgbouncer.query_wait_timeout | int | 120 | Maximum time in seconds a query waits in the queue. When the timeout is reached, the client is disconnected. Set to 0 for an indefinite wait. |
pgbouncer.ignore_startup_parameters | string | "extra_float_digits" | Comma-separated list of startup parameters PgBouncer ignores. By default, PgBouncer only processes core parameters (client_encoding, datestyle, timezone, standard_conforming_strings) and rejects connections that send unknown parameters. Add any extra parameters here. Always keep extra_float_digits to maintain compatibility with PostgreSQL JDBC (Java Database Connectivity) drivers. |
pgbouncer.stats_users | string | "" | Comma-separated list of users allowed to connect to the PgBouncer virtual database and run read-only queries. |
For the full parameter reference, see the official PgBouncer documentation.
View connection pool metrics
Use Enhanced Monitoring to monitor connection pool activity. Metrics are available only after PgBouncer is enabled.
| Metric | Description |
|---|---|
db.pgbouncer.client_connections.active | Active client connections |
db.pgbouncer.client_connections.waiting | Client connections waiting for a backend connection |
db.pgbouncer.server_connections.active | Active backend connections |
db.pgbouncer.server_connections.idle | Idle backend connections |
db.pgbouncer.total_pooled_connections | Total connections in the pool |
db.pgbouncer.num_pools | Number of connection pools |
Limitations
The maximum idle time for a connection in the pool is 10 minutes. Idle connections that exceed this duration are automatically closed. This value cannot be changed.
When SSL encryption is enabled on the instance, PgBouncer also enables SSL. PgBouncer does not support connection authentication with the Access Control List (ACL) set to
verify-caorverify-full, and does not support client certificate revocation files.
API reference
Call the ModifyDBInstanceConfig operation to enable or disable PgBouncer programmatically.
| Parameter | Description | Example |
|---|---|---|
DBInstanceId | The ID of the RDS for PostgreSQL instance | pgm-**** |
ConfigName | The name of the configuration item | pgbouncer |
ConfigValue | true to enable, false to disable | true |