PolarProxy is a built-in proxy layer that sits between your application and a PolarDB cluster. It intercepts all inbound requests and routes them intelligently across the primary node and read-only nodes, giving you automatic read/write splitting, load balancing, connection pooling, configurable consistency levels, and overload protection—without any changes to your application connection string.
Connect to a cluster endpoint to start using PolarProxy features.
When to use PolarProxy
PolarProxy addresses three common operational challenges:
High read traffic: Route read requests across multiple read-only nodes to distribute load and reduce pressure on the primary node.
Connection storms: Use the connection pool to multiplex thousands of application connections onto a smaller number of database connections, preventing overload during traffic spikes.
Mixed workload isolation: Create multiple cluster endpoints—each in read/write or read-only mode—to physically separate different applications or traffic types. For example, assign two read-only nodes to a dedicated read-only endpoint for reporting jobs, while keeping the remaining nodes for transactional traffic.
Architecture
A PolarDB Cluster Edition cluster has one primary node and multiple read-only nodes. The cluster provides two endpoint types by default:
Primary endpoint: Routes all traffic directly to the primary node.
Cluster endpoint: Provided by PolarProxy. Supports read/write mode (automatic read/write splitting) and read-only mode.
PolarProxy Enterprise editions
PolarProxy Enterprise Edition is available in two editions that match your cluster type.
Standard Enterprise Edition is used by General-purpose clusters. It runs on shared physical CPU resources with smart elastic scalability. By default, it is allocated CPU cores equal to one-sixth of the total CPU cores across all nodes in the cluster.
Dedicated Enterprise Edition is used by Dedicated clusters. It runs on exclusive physical CPU resources for better performance stability. By default, it is allocated CPU cores equal to one-fourth of the total CPU cores across all nodes in the cluster.
In both editions, PolarProxy CPU resources are allocated independently from the cluster's compute nodes.
The following table shows where the two editions differ.
| Feature | Standard Enterprise Edition | Dedicated Enterprise Edition |
|---|---|---|
| Resource type | Shared physical CPU with elastic scalability | Exclusive physical CPU for stable performance |
| Compute node scale-out | Elastic, within seconds | Exclusive resource reservation ensures availability |
Both editions share the following capabilities:
Free of charge
High-availability redundant architecture
Minimum cluster specification: 2 cores
No limit on the number of connections to a cluster endpoint
Maximum cluster storage IOPS increased by 50% compared to previous editions (see Compute node specifications of PolarDB for MySQL Enterprise Edition for per-specification limits)
Read-only node configurations do not need to match the primary node—you can downgrade read-only node specifications based on business loads to reduce costs
Up to 15 read-only nodes
One primary endpoint and seven cluster endpoints
Failover with hot standby: connections are temporarily blocked for 5–10 seconds, but not dropped
Consistency levels: eventual consistency, session consistency, and global consistency
Connection pool, transaction splitting, interruption protection (persistent connections), data masking, business stability during configuration changes, Multi-master Cluster (Database/Table), and proxy throttling protection (available soon)
Billing
PolarProxy Enterprise Edition is free of charge.
The following table describes how existing clusters were migrated to PolarProxy Enterprise Edition.
| Purchase type | Switching policy |
|---|---|
| Newly purchased cluster | As of December 9, 2021, all new clusters use PolarProxy Enterprise Edition. |
| Existing pay-as-you-go cluster | Automatically switched to PolarProxy Enterprise Edition on December 9, 2021. |
| Existing subscription cluster | Automatically switched to PolarProxy Enterprise Edition on December 9, 2021. |
Limitations
Only PolarDB Cluster Edition clusters support cluster endpoints and PolarProxy.
Usage notes
Read/write splitting behavior
Without transaction splitting enabled, all requests within a transaction are forwarded to the primary node.
Executing multi-statement queries or calling stored procedures causes all subsequent requests on that connection to be forwarded to the primary node. To resume read/write splitting, close the connection and reconnect.
Do not modify environment variables (such as
SET NAMES utf8mb4) within a multi-statement batch (for example,SET NAMES utf8mb4;SELECT * FROM t1;). Doing so can cause data inconsistency between the primary node and read-only nodes.Running
SHOW PROCESSLISTthrough a cluster endpoint returns results from all nodes in the cluster.
Connection routing for new or restarted read-only nodes
Sessions created after you add or restart a read-only node automatically route read requests to that node. Sessions created before the add or restart continue routing to the previous set of nodes. To include the new or restarted node, close the existing connection and reconnect—for example, by restarting your application.
Connection limits
The cluster endpoint itself has no hard connection limit. The effective maximum depends on your compute node specifications:
Read/write splitting mode: The maximum connections equal the maximum connections of a single compute node, because the application establishes a connection to each node in the cluster.
Read-only mode: The maximum connections equal the sum of the maximum connections of all read-only nodes associated with the endpoint.
To increase the effective connection limit in read/write splitting mode, enable the transaction-level connection pool. For details, see the "Transaction-level connection pools" section in Connection pools.
Compression protocols
PolarProxy does not support compression protocols for default or custom cluster endpoints.
Application connection pool timeout parameters
To prevent hung connections caused by packet loss or other network issues when using an application-side connection pool, add connectTimeout and socketTimeout to your connection URL. For parameter details, see Parameters.
Example Java URL:
jdbc:mysql://ip:port/db?connectTimeout=60000&socketTimeout=300000Upgrade the specifications of PolarProxy
The default specifications of PolarProxy Enterprise Edition are enough for most workloads. Specifications scale up automatically in real time based on observed load, so no manual action is needed in most cases.
For clusters running previous PolarProxy versions, manual specification upgrades are also supported.
Upgrading PolarProxy specifications does not consume or reduce the CPU cores allocated to your cluster's compute nodes, because PolarProxy runs on separate resources. No additional charges apply—PolarProxy Enterprise Edition is free.
For upgrade instructions, see Upgrade the specifications of PolarProxy.
API reference
| Operation | Description |
|---|---|
| CreateDBEndpointAddress | Creates a public endpoint for a PolarDB cluster. |
| CreateDBClusterEndpoint | Creates a custom endpoint for a PolarDB cluster. |
| DescribeDBClusterEndpoints | Queries the endpoint information of a PolarDB cluster. |
| ModifyDBClusterEndpoint | Modifies the configuration of a cluster endpoint. |
| ModifyDBEndpointAddress | Modifies the addresses of cluster endpoints, including custom endpoints. |
| DeleteDBEndpointAddress | Deletes a cluster endpoint. Cannot be used to delete private custom cluster endpoints. |
| DeleteDBClusterEndpoint | Deletes a custom cluster endpoint. |