PolarDB clusters route connections through endpoints rather than direct node addresses. This means you don't need to hardcode hostnames or manage failover logic in your application — PolarDB handles routing automatically based on which endpoint you use. Each endpoint type serves a different purpose, so choosing the right one affects read/write splitting, failover behavior, and whether you can execute DDL statements.
Endpoint types
PolarDB for PostgreSQL supports three endpoint types:
| Endpoint | Use when | Supported networks |
|---|---|---|
| Cluster endpoint (recommended) | Running reads and writes for most applications. Automatically splits read traffic across read-only nodes and routes writes to the primary node. Available only on centralized clusters (Enterprise Edition or Standard Edition). | Private, public |
| Primary endpoint | Executing DDL statements, or connecting directly to the primary node. Each cluster has exactly one primary endpoint. Automatically reconnects to the new primary node after a failover. | Private, public |
| Custom endpoint | Directing traffic to a specific set of read-only nodes, or applying a distinct read/write mode or load balancing policy. | Private, public |
Distributed clusters do not have a cluster endpoint. For most operations, use the primary endpoint. To execute DML and DQL statements across multiple compute nodes (CNs), use a custom endpoint. DDL statements — such as creating or dropping tables and accounts — must go through the primary endpoint.
Choose an endpoint
Use the following guidance to select the endpoint that fits your workload:
General application traffic (reads and writes): Use the cluster endpoint. It provides automatic read/write splitting and is the most resilient option for production workloads on centralized clusters.
DDL operations or direct primary node access: Use the primary endpoint. It automatically reconnects after a failover, but does not provide read/write splitting.
Traffic isolation for specific read-only nodes: Use a custom endpoint. This lets you apply dedicated load balancing policies or direct queries to a specific subset of nodes.
Temporary maintenance from outside your virtual private cloud (VPC): Apply for a public endpoint on any of the above endpoint types. See Apply for a public endpoint.
Custom endpoint limits
Centralized clusters (Enterprise Edition or Standard Edition):
Up to five custom endpoints per cluster
Powered by PolarProxy; supports read/write splitting or read-only mode
Routes requests to one or more associated read-only nodes
If a custom endpoint is associated with only one node and that node fails, the endpoint may be unavailable for up to 1 hour. In production environments, associate at least two nodes with each custom endpoint.
Distributed clusters:
Up to six custom endpoints per cluster
The unified CN endpoint supports DML and DQL only — use the primary endpoint for DDL
Private and public endpoints
By default, each cluster has a private endpoint. A public endpoint is optional and must be applied for separately.
| Network type | Description | When to use |
|---|---|---|
| Private | Default; optimal performance. Can be modified but not released. | Your Elastic Compute Service (ECS) instance is in the same VPC as the cluster, or you use Data Management (DMS) to connect across VPCs. |
| Public | Internet-accessible; lower performance than private. Apply for or delete as needed. | Connecting from outside the VPC — for example, from a local machine for temporary maintenance. |
View endpoints and ports
Log on to the PolarDB console. In the left-side navigation pane, click Clusters. Select the region where the cluster resides, then click the cluster ID to go to the Basic Information page.
Follow the steps for your cluster type.
Centralized cluster
In the Database Connections section, hover over an endpoint. The Network Information dialog shows the full endpoint address and port number.
To retain an existing database domain name after migrating to the cloud, click Bind Private Domain Name to bind a domain name to a private endpoint. Domain name binding is supported for private endpoints only. For details, see .
Distributed cluster
In the Database Connection section, hover over the private or public endpoint. The dialog shows the endpoint address and port number.
Apply for a public endpoint
Apply for a public endpoint when you need to connect to the cluster over the internet. Common scenarios include:
Connecting from a local machine for temporary maintenance
Accessing the cluster from outside Alibaba Cloud
Public endpoints have lower performance than private endpoints. Use a private endpoint for production traffic whenever possible.
Log on to the PolarDB console. In the left-side navigation pane, click Clusters. Select the region where the cluster resides, then click the cluster ID to go to the Basic Information page.
Follow the steps for your cluster type.
Centralized cluster
Private endpoints are created automatically when you create a cluster or a custom endpoint. Only public endpoints require a manual application.
In the Database Connections section of the Basic Information page, find the endpoint and click Apply to the right of the Public parameter.
In the dialog that appears, enter a prefix for the endpoint and click OK. The prefix must meet these requirements:
6–40 characters
Lowercase letters, digits, and hyphens (-) only
Starts with a letter; ends with a letter or digit
Distributed cluster
In the Database Connections section of the Basic Information page, find the endpoint and click Apply to the right of Public Endpoint.
In the dialog that appears, enter a prefix for the endpoint and click OK. The prefix must meet these requirements:
6–40 characters
Lowercase letters, digits, and hyphens (-) only
Starts with a letter; ends with a letter or digit
What to do next
Connect to your cluster using the endpoint and port you retrieved. For details, see Connect to a cluster.
API reference
| Operation | Description |
|---|---|
| DescribeDBClusterEndpoints | Queries the endpoints of a specified PolarDB cluster |
| CreateDBEndpointAddress | Creates a public endpoint for a PolarDB cluster |
| Modifies the endpoints of a PolarDB cluster | |
| DeleteDBEndpointAddress | Deletes the public endpoints of a PolarDB cluster |