What are the endpoints of a PolarDB cluster - PolarDB - Alibaba Cloud Documentation Center

To connect your application to a PolarDB cluster, you use an endpoint that contains a host address and a port provided in the connection string for any script, utility, or application. For most use cases, we recommend using the cluster endpoint for all connections to your cluster. This ensures your connections are highly available and automatically leverage the read-only nodes for scaling. For more specialized use cases, PolarDB also provides custom and primary endpoints. This guide describes the different types of endpoints and how to use them effectively.

Comparison between cluster endpoints and primary endpoints

Every PolarDB cluster has 3 types of endpoints, each designed for a specific use case. The Cluster and Custom endpoints are powered by the managed PolarProxy, which provides advanced features like read/write splitting, load balancing, and connection pooling.

Type	Description	Use cases	Supported network types
Default cluster endpoint (Recommended)	A single endpoint that connects to the current primary node of the cluster. Provided by PolarProxy, it supports automatic read/write splitting. Write requests are routed to the primary node and read requests are routed to read-only nodes.	Businesses that require read/write splitting and can scale out quickly in real time by adding read-only nodes.	Private network Public network
Custom endpoint	A user-defined endpoint that connects to a specific subset of nodes within the cluster. You can configure which nodes (primary or read-only) a custom endpoint routes traffic to, along with its read/write mode and load balancing policy. A custom endpoint must be attached to at least one read-only node. Requests sent to this endpoint are routed only to the attached read-only node. Note Single-node custom endpoints are intended for development or testing purposes only and should never be used in production. These endpoints provide no high availability. If the underlying node fails, the endpoint will become unavailable for up to one hour, causing an outage for any connected applications.	Isolating database node access for different services. For example, if read-only node 5 in the preceding figure fails, only Service Z is affected. By setting the read/write mode to Read-only, you can configure the endpoint to support only read-only services.
Primary endpoint	A single primary endpoint that connects to a specific database node, bypassing the PolarProxy. It always connects to the primary node and supports both read and write operations. If the primary node fails, the primary endpoint automatically switches to the new primary node.	Businesses that do not require read/write splitting.

Private and public endpoints

Endpoints can be configured with different network types to control access.

Network type

Description

Use cases

Private network (VPC)

Provides the best performance and security by keeping traffic within your Virtual Private Cloud (VPC). This is the recommended network type for production applications.
When you create a cluster, a private endpoint is generated by default. You can modify this endpoint but cannot release it. See Change the endpoint of a cluster for details.

Examples:

If an ECS instance and a database cluster are in the same VPC, the ECS instance can access the database cluster through a private endpoint.
Use DMS to access the database cluster through a VPC.

Public network

Allows connections over the public internet. This is useful for development, remote management, or connecting from services outside your VPC, but it does not offer optimal performance and requires careful security management.
You can request or release a public endpoint. See Manage the endpoints of a cluster for details.

For example, access the database cluster through a public endpoint for maintenance operations.

Read/write modes for cluster endpoints

Cluster endpoints support two read/write modes: Read/Write (Automatic Read/Write Splitting) and Read-only. The following table describes the differences between the two modes.

Note

For instructions on how to set the read/write mode for a cluster endpoint, see Configure PolarProxy.

Item	Read/Write (Automatic Read/Write Splitting)	Read-only
Service node selection method	The following three methods are supported: Select only the primary node. Select one or more read-only nodes. Select the primary node and one or more read-only nodes. Note In read/write splitting mode: All write requests are sent to the primary node, regardless of whether the primary node is added as a service node. For read requests, you can use the Primary Node Accepts Read Requests setting to determine whether the primary node processes read requests.	Only the following method is supported: Select one or more read-only nodes. Note In read-only mode: All read requests are forwarded to the read-only nodes based on the load balancing policy. No requests are forwarded to the primary node, even if it is added as a service node. You cannot create a read-only cluster endpoint that contains only a primary node.
Load Balancing Policy	Supports the Active Request-based Load Balancing policy. See Load balancing policies.	Connections-based Load Balancing and Active Request-based Load Balancing are supported. For more information, see Load balancing policy.
Primary Node Accepts Read Requests	Supported. See Features for details.	This feature is not applicable because it is designed to reduce the load on the primary node. The primary node for a Read-only endpoint does not process any read or write requests.
Transaction Splitting	Supported. See Transaction splitting. Note This configuration is supported only if Consistency Level is set to Session Consistency (Medium) or Global Consistency (Strong).	This feature is not applicable because it is designed to reduce the load on the primary node. The primary node for a Read-only endpoint does not process any read or write requests.
Consistency Level	Supports Eventual Consistency (Weak), Session Consistency (Medium), and Global Consistency (Strong). See Consistency level.	Only Eventual Consistency (Weak) is supported because this endpoint does not perform write operations.
Connection Pool	Supports Session-level and Transaction-level connection pools. For more information, see Connection pool. Note The connection pool is a feature of the PolarDB PolarProxy and does not affect the connection pool feature on your client. If your client provides a connection pool, you can select Off to disable the PolarProxy connection pool feature. If you turn Off the proxy's connection pool feature, client connections are routed through the proxy to all nodes configured for the endpoint, including the primary and read-only nodes. The total number of available business connections is then limited by the maximum connections of the primary node.	Not supported. Note PolarDB evenly distributes connections among all read-only nodes that are configured for the Read-only cluster endpoint. The primary node does not participate in connection distribution. A client connection is routed through the proxy to a single read-only node. The total number of available connections is the sum of the maximum connections for all read-only nodes.
Security Protection	Supported. See Overload protection.	Not supported.

FAQ

How can I determine from session information whether my application is connected to a primary endpoint or a cluster endpoint?

You can determine this in two ways:

By Session ID:
If the session ID is less than 16777215, the connection is to the primary address. Otherwise, the connection is to a cluster address.
By the Vip Field in SQL Insight:
Navigate to the Audit tab within SQL Explorer. If the Vip field contains a value, the connection is to a cluster address or a custom address. If the field is empty, it could mean one of two things:
- The connection is to the primary address.
- The connection is to a cluster address, but the database kernel version is too old to output the Vip information. For example, for MySQL 8.0.1, the minor kernel version must be 8.0.1.1.3 or later.
In the latter case, we recommend upgrading your database kernel version to reliably use the Vip field for this check.

How can I determine whether the current session is connected to a default cluster endpoint or a custom endpoint?

Check the Vip field on the Audit tab of SQL Explorer. The IP address displayed in this field is the IP of the cluster or custom address.

If this field is empty, it may be because the database kernel version is too old to output this information. For example, for MySQL 8.0.1, the minor kernel version must be 8.0.1.1.3 or later. In this situation, we recommend upgrading your database kernel version.

How can I connect directly to a read-only node?

You can create a dedicated endpoint for read-only nodes by creating a custom address. Connections made using this new endpoint will be routed exclusively to the read-only nodes you select.

Procedure:

Log on to the PolarDB console. On the Basic Information page of your cluster, find the Database Connections section and click Create Custom Endpoint.
In the Create Custom Endpoint dialog box, set the Read/Write Mode to Read-only, select the desired read-only nodes, and click OK.
Once the custom endpoint is created, you can use its connection string to connect directly to the specified read-only nodes.