PolarDB exposes three types of connection endpoints — each a combination of a host address and a port. Choosing the right endpoint type and network configuration determines how your application handles read/write splitting, failover, and traffic isolation.
Choose an endpoint
The cluster endpoint is the right choice for most workloads.
| Endpoint type | What it does | When to use it | Supported network types |
|---|---|---|---|
| Cluster endpoint (recommended) | Routes traffic through PolarProxy, which automatically splits read and write requests — writes go to the primary node, reads are distributed across read-only nodes. | Use for most workloads. Provides read/write splitting, load balancing, and connection pooling. Scale reads by adding read-only nodes at any time. |
|
| Custom endpoint | A user-defined endpoint that routes to a specific subset of nodes. Configure which nodes to include, the read/write mode, and the load balancing policy. | Use to isolate traffic for specific services — for example, route analytics queries to a dedicated set of read-only nodes without affecting your production workload. | Private network (VPC), public network |
| Primary endpoint | Connects directly to the primary node, bypassing PolarProxy. Supports both reads and writes. | Use when your application requires direct database connections and cannot work with read/write splitting. | Private network (VPC) |
Custom endpoint constraints
A custom endpoint must include at least one read-only node. Requests are routed only to the nodes attached to the endpoint.
Single-node custom endpoints provide no high availability. If the underlying node fails, the endpoint is unavailable for up to one hour. Use single-node custom endpoints for development and testing only — never in production.
Behavior during node failures
| Endpoint type | Behavior when a node fails |
|---|---|
| Custom endpoint (single-node) | Endpoint becomes unavailable for up to one hour. |
| Primary endpoint | Automatically reconnects to the new primary node after a failover. |
Choose a network type
| Network type | Description | Typical use cases |
|---|---|---|
| Private network (VPC) | Keeps traffic within your Virtual Private Cloud (VPC). Provides the best performance and security. A private endpoint is created automatically when you create a cluster. You can modify it but cannot delete it. See Change the endpoint of a cluster. | An Elastic Compute Service (ECS) instance and the cluster are in the same VPC. Accessing the cluster through Data Management Service (DMS) over VPC. |
| Public network | Allows connections over the internet. Less performant than VPC and requires careful access control. You can create or release a public endpoint at any time. See Manage the endpoints of a cluster. | Remote administration. Connecting from services or tools outside your VPC. |
Use the private network for all production traffic. Reserve public endpoints for development, remote management, or when VPC access is not available.
Read/write modes for cluster endpoints
Cluster endpoints support two read/write modes. Choose based on whether the endpoint needs to handle writes.
To configure the read/write mode for a cluster endpoint, see Configure PolarProxy.
Read/write (automatic read/write splitting)
Writes go to the primary node. Reads are distributed across whichever nodes you configure as service nodes.
-
Service node selection: Include the primary node, one or more read-only nodes, or both.
-
Write routing: All write requests go to the primary node regardless of service node configuration.
-
Read routing: Controlled by the Primary Node Accepts Read Requests setting — toggle this to include or exclude the primary node from read traffic.
-
Load balancing: Active Request-based Load Balancing. See Load balancing policies.
-
Transaction splitting: Supported when Consistency Level is set to Session Consistency (Medium) or Global Consistency (Strong). See Transaction splitting.
-
Consistency level: Supports Eventual Consistency (Weak), Session Consistency (Medium), and Global Consistency (Strong). See Consistency level.
-
Connection pool: Session-level or Transaction-level. See Connection pool.
The PolarProxy connection pool is independent of any client-side connection pool. If your client already manages a connection pool, set the PolarProxy connection pool to Off. When set to Off, connections are distributed across all configured nodes, and the total connection limit is determined by the primary node's maximum connections.
-
Security protection (overload protection): Supported. See Overload protection.
FAQ
How can I tell whether my connection is going to a primary endpoint or a cluster endpoint?
Check the session ID or the Vip field in SQL Explorer.
-
Session ID: If the session ID is less than
16777215, the connection is using the primary endpoint. Otherwise, it is using a cluster endpoint. -
`Vip` field in SQL Explorer: Go to the Audit tab in SQL Explorer. If the
Vipfield contains an IP address, the connection is using a cluster or custom endpoint. If the field is empty, either the connection is using the primary endpoint, or the database kernel version is too old to populate the field. For MySQL 8.0.1, the minor kernel version must be 8.0.1.1.3 or later. If you rely on this field for diagnostics, upgrade your database kernel.
How can I tell whether I'm connected to the default cluster endpoint or a custom endpoint?
Check the Vip field on the Audit tab of SQL Explorer. The IP address shown is the IP of the cluster or custom endpoint. If the field is empty, the database kernel version may be too old to output this information — for MySQL 8.0.1, the minor kernel version must be 8.0.1.1.3 or later.
How do I connect directly to a read-only node?
Create a custom endpoint with Read/Write Mode set to Read-only and add the desired read-only nodes. All connections through that endpoint go exclusively to those nodes.
-
Log on to the PolarDB console. On the Basic Information page of your cluster, go to the Database Connections section and click Create Custom Endpoint.
-
In the Create Custom Endpoint dialog, set Read/Write Mode to Read-only, select the read-only nodes to include, and click OK.
-
Use the new endpoint's connection string to connect directly to those read-only nodes.