PolarDB supports two connection pool types: session-level and transaction-level. Connection pools reduce database connection overhead by reusing existing connections instead of establishing new ones for each request.
The connection pool described here is a feature of PolarProxy—the proxy layer of PolarDB. It does not affect any connection pool built into your application. If your application already manages its own connection pool, you do not need to enable this feature.
How it works
Session-level connection pool
When an application connection closes, PolarProxy checks whether it is idle. If idle, PolarProxy retains it in the pool for a short period. The next incoming request reuses that idle connection if the user, clientip, and dbname parameters match—saving the cost of opening a new connection. If no match is found, PolarProxy opens a new connection to the database.
Session-level pools reduce how often connections are established, which lowers the number of MySQL main threads consumed and improves throughput. They do not reduce the total number of concurrent connections; idle connections still count toward the database connection limit.
Transaction-level connection pool
A transaction-level pool reduces both the number of direct connections to the database and the overhead from short-lived connections. Applications can open thousands of connections to PolarProxy while PolarProxy maintains only dozens or hundreds of connections to backend databases.
When an application sends a request, PolarProxy does not immediately open a backend connection. It checks the pool for an idle connection matching the user, dbname, and system variables (sql_mode, character_set_server, collation_server, time_zone). If a match exists, PolarProxy reuses it. After the transaction completes, the connection returns to the pool for other requests.
PolarProxy does not enforce a connection count limit on the application side. The maximum connections to a PolarDB cluster endpoint depend on the specifications of backend compute nodes. Without a transaction-level pool, the system must open a separate connection on the primary node and on each read-only node for every request.
Choose a connection pool
Use this table to match your scenario to the right pool type:
| Scenario | Recommended pool | Reason |
|---|---|---|
| Few connections, mostly persistent, or application already has its own pool | None (disable) | A PolarDB pool adds overhead without benefit |
| Tens of thousands of connections, or serverless with connections that scale linearly | Transaction-level | Multiplexes many application connections into fewer backend connections |
| Short-lived connections only, in scenarios listed under Transaction-level limitations | Session-level | Reduces connection frequency without requiring full multiplexing |
Frequent COM_STATISTICS execution | None (disable) | Enabling the pool converts non-persistent connections to persistent ones, increasing the number of persistent connections and triggering a lock-then-traverse bottleneck in COM_STATISTICS. Frequent executions may cause serious performance degradation and affect the response time of the overall business. |
| Large number of slow SQL statements causing pending connections | None (disable) | Connection pools do not resolve slow-query contention; reduce slow queries instead |
Limitations
Session-level limitations
Session-level pools reduce connection frequency, not concurrency. Idle pooled connections still count toward the database's total connection limit.
Session-level pools do not resolve pending connections caused by slow SQL statements.
Transaction-level limitations
The following operations lock the connection for the duration of the session. A locked connection is not returned to the pool and becomes unavailable to other requests.
| Operation | Workaround |
|---|---|
Execute a PREPARE statement | Use client-side prepared statements if your driver supports them |
| Create a temporary table | Use a regular table with a unique session identifier, then drop it when done |
| Modify user variables | Set variables at session start, or pass values explicitly in each query |
| Receive log entries exceeding 16 MB | Break large log writes into smaller batches |
Execute a LOCK TABLE statement | Use row-level locking (SELECT ... FOR UPDATE) instead |
| Execute multiple statements in a single statement string | Split into individual statements |
| Call a stored procedure | Migrate logic to the application layer where possible |
Unsupported functions
FOUND_ROWS(), ROW_COUNT(), and LAST_INSERT_ID() can be called but may return inaccurate results when connections are reused.
| Function | Workaround |
|---|---|
FOUND_ROWS() | On PolarProxy V1.13.11 or later, place SELECT FOUND_ROWS() immediately after SELECT SQL_CALC_FOUND_ROWS * FROM t1 LIMIT *. Note that this method is no longer recommended by open source MySQL. Alternatively, replace it with SELECT COUNT(*) FROM tb1. For details, see FOUND_ROWS(). |
LAST_INSERT_ID() | Place SELECT LAST_INSERT_ID() immediately after the INSERT statement to get accurate results. |
ROW_COUNT() | No workaround available; the function can be invoked but may return inaccurate results when connections are reused. |
Other behavioral differences
`wait_timeout`: When the timeout elapses, only backend connections are closed. Application-side connections to PolarProxy stay open because PolarProxy selects a connection from the pool for each new request.
Session variables: The pool matches connections using
sql_mode,character_set_server,collation_server, andtime_zone. If your requests depend on other session-level system variables, runSETstatements to configure them after each connection is established. Otherwise, the pool may reuse a connection with unexpected variable values.`SELECT connection_id()`: May return different thread IDs for what appears to be the same connection, because connections are reused across requests.
`SHOW PROCESSLIST` and SQL Explorer: The IP addresses and port numbers shown may differ from your application's actual IP address and port, because connections are multiplexed through PolarProxy.
`KILL` command: Returns
ERROR 1094 (HY000): Unknown thread id: xxxbecause the thread ID between the client and PolarProxy differs from the thread ID between PolarProxy and the database. PolarProxy mergesSHOW PROCESSLISTresults from all nodes before returning them to the client.
Usage notes
Connection pool settings take effect only on connections created after the change. Existing connections are not affected. For configuration steps, see Configure PolarProxy.
The connection pool does not support IP-specific permissions for an account. If you grant
user@192.xx.xx.1access todatabase_abut notuser@192.xx.xx.2, a permission error may occur when that connection is reused. Avoid configuring different permissions for the same account across different IP addresses when connection pooling is enabled.