Connection pool best practices | Redis cluster proxy - Tair (Redis® OSS-Compatible)

Scenarios

In cloud native cluster proxy mode, standard commands use shared connections, so client connection growth does not affect backend DB connections. However, certain stateful commands switch the proxy-to-data-node connection from shared to exclusive mode.

In exclusive mode, each client connection creates a dedicated connection on the data node. Under high concurrency, data node connections grow linearly with client connections, potentially triggering a max number of clients reached error and causing service interruptions.

Scaling out by adding shards does not resolve per-shard connection exhaustion caused by watch or blocking requests.

Commands that trigger exclusive mode:

Transaction commands: MULTI/EXEC (after WATCH)
Blocking commands: BLPOP, BRPOP, BRPOPLPUSH, and XREAD ... BLOCK ...

The connection pool reuses exclusive proxy-to-data-node connections, reducing data node connections and preventing failures from exceeding the connection limit.

Architecture

Each proxy child instance runs an independent connection pool and maintains a dedicated pool for each data node.

Example:

Without a connection pool, each client-proxy connection establishes a separate connection to each backend shard. For example, 10 client connections accessing 5 shards create 10 × 5 = 50 connections.

With connection pooling enabled, the proxy maintains a limited pool for each shard, and client requests reuse pooled connections. For example, the same 10 client connections may require only 2 pooled connections per shard, totaling 2 × 5 = 10 connections.

Workflow:

When a client initiates an exclusive-mode request, the proxy retrieves an idle connection from the target shard's connection pool.
Pool hit: An idle connection is attached to the client connection for the request. After completion, the connection is detached and returned to the pool for reuse.
Pool miss: The proxy creates a new connection. After the request completes:
1. If the pool has not reached the limit (private_conn_pool_max_idle_per_db), the connection is added to the pool.
2. If the pool is full, the connection is released immediately (short-lived connection mode).

This reduces connection management overhead, lowers resource consumption on the database, and improves stability and throughput.

Requirements

Your instance must meet these requirements:

Deployment mode: Cloud native. You can change from classic to cloud native.
Instance architecture: Cluster. You can change the architecture from standard to cluster.
Connection mode: Proxy mode.
Proxy version: 7.0.17 or later. If your version is earlier, you can upgrade the proxy version.

Enable connection pooling

Enable connection pooling by modifying an instance parameter. This is a hot update that does not require a restart or affect running services.

Go to the Instances page. In the top navigation bar, select a region. Then, click the ID of the target instance.
In the left navigation pane, click Parameter Settings.
Find private_conn_pool_enabled and click Modify in the Actions column.
In the dialog box, set the value to 1 and click OK.

To verify, check the Connections from Proxy to DB metric under Infrastructure Monitoring in the Cloud Monitor console to compare the data before and after enabling the feature.

Configuration and tuning

Configuration name	Description	Default value	Value range
`private_conn_pool_enabled`	Enables or disables connection pooling. `1`: enabled. `0`: disabled.	0	`[0\|1]`
`private_conn_idle_time_sec`	TTL for idle connections in the pool, in seconds. Connections idle beyond this threshold are closed. `0`: close immediately.	60	`[0-4294967295]`
`private_conn_pool_max_idle_per_db`	Maximum idle connections each proxy node maintains per data node. When this limit is reached, released connections are closed instead of returned to the pool.	1000	`[0-4294967295]`
`private_conn_pool_min_idle_per_db`	Minimum idle connections each proxy node maintains per data node. Connections below this threshold are retained even if they exceed `private_conn_idle_time_sec`.	0	`[0-4294967295]`

Tuning recommendations

General scenarios: Use the default values. They suit most workloads.
High-concurrency, short-lived transaction scenarios (such as flash sales)
- Characteristics: Short-lived connections with frequent borrow/return cycles.
- Recommendation: Set private_conn_pool_max_idle_per_db high enough to cover peak concurrent requests, maximizing reuse and avoiding short-lived connections. Optionally lower private_conn_idle_time_sec to release resources faster during off-peak hours.
Long-blocking service scenarios (such as queue consumers)
- Characteristics: Long-held connections rarely returned to the pool.
- Recommendation: Increase private_conn_pool_max_idle_per_db to match concurrent consumer count. Set private_conn_pool_min_idle_per_db slightly above the average concurrent connections to prefetch connections and reduce latency for new consumers.
Memory-constrained or small instance scenarios
- Characteristics: Strict memory budget.
- Recommendation: Lower private_conn_pool_max_idle_per_db and private_conn_pool_min_idle_per_db. This trades some reuse efficiency for reduced memory consumption on data nodes.

Usage notes

Set a reasonable value for private_conn_pool_min_idle_per_db

Each idle connection consumes memory on the backend DB node. With multiple shards and proxy nodes, a high private_conn_pool_min_idle_per_db value can cause excessive memory usage.
Avoid unnecessary DB context switching

When a pooled connection is reused by a client accessing a different DB index, the proxy runs a SELECT command to switch context, increasing DB payload and latency. Design your application to use a single DB index (typically DB 0).
Not applicable to publish/subscribe commands

Connection pooling does not apply to SUBSCRIBE and PSUBSCRIBE commands. These permanently occupy a connection and are not managed by the pool.

Tair (Redis® OSS-Compatible):Connection pool best practices for cluster proxy mode