A cluster endpoint is the connection address through which your application connects to a PolarDB cluster. PolarDB creates a default cluster endpoint for every cluster. By creating a custom cluster endpoint, you can independently configure read/write splitting, load balancing, transaction splitting, consistency levels, and connection pooling for specific workloads — without affecting other endpoints.
When to create a custom cluster endpoint:
Route reporting or analytics traffic to read-only nodes, keeping the primary node reserved for write-heavy production traffic.
Apply different consistency levels to different application tiers (for example, strong consistency for order processing, eventual consistency for product catalog reads).
Enable transaction-level connection pooling only for workloads that open many short-lived connections (such as serverless functions or batch jobs).
Prerequisites
Before you begin, ensure that you have:
Access to the PolarDB console
PolarDB PostgreSQL distributed clusters do not support database proxy configuration. This page applies to PolarDB for Oracle clusters.
Create a custom cluster endpoint
Log on to the PolarDB console. In the left navigation pane, click Clusters. Select the region of your cluster and click the cluster ID.
On the Basic Information page, go to the Database Connections section and click Create Custom Cluster Endpoint.
In the Create Custom Cluster Endpoint dialog, configure the following settings.
Click OK.
Network information
By default, PolarDB assigns a private endpoint to each cluster endpoint. To modify the endpoint address or request a public endpoint, see Modify an endpoint and Apply for an endpoint.
Cluster settings
| Setting | Description |
|---|---|
| Read/Write | The read/write mode for this endpoint. Select Read-only or Read/Write (Automatic Read/Write Splitting). |
| Endpoint name | A name for the custom cluster endpoint. |
Changing the read/write mode applies only to new connections. Existing connections retain their original mode until they reconnect.
Node settings
| Setting | Description |
|---|---|
| Available nodes and Selected nodes | Select nodes to process read requests for this endpoint. Move nodes from the Available nodes list to the Selected nodes list by clicking the  icon. Available nodes includes the primary node and all read-only nodes. |
| Automatically associate new nodes | Enabled: New nodes added to the cluster are automatically included in this endpoint. Disabled: Only the nodes you selected at creation time are included. New nodes are not added automatically. |
Node selection does not affect the read/write mode. In Read/Write (Automatic Read/Write Splitting) mode, write requests always go to the primary node regardless of node selection. A single-node endpoint is supported, except when the read/write mode is Read-only and only the primary node is selected.
Load balancing settings
| Setting | Description |
|---|---|
| Load balancing policy | The scheduling policy for distributing read requests across nodes. In Read-only mode, select Load balancing based on the number of connections or Load balancing based on the number of active requests. In Read/Write (Automatic Read/Write Splitting) mode, the policy is fixed to Load balancing based on the number of active requests and cannot be changed. |
| Primary node accepts read requests | Disabled (default): Read requests can also be sent to the primary node. Enabled: Read requests go only to read-only nodes, reducing load on the primary node. Available only in Read/Write (Automatic Read/Write Splitting) mode. For details, see Read/write splitting. |
Transaction splitting
Enable or disable transaction splitting. When enabled, read statements within a transaction that has not yet executed a write operation are sent to read-only nodes. This reduces the load on the primary node without breaking transaction semantics. Available only in Read/Write (Automatic Read/Write Splitting) mode. For details, see Transaction splitting.
Consistency settings
| Setting | Description |
|---|---|
| Consistency level | Controls whether read queries see the latest writes. Available only in Read/Write (Automatic Read/Write Splitting) mode; Read-only mode is fixed to Eventual Consistency (Weak). See below or the Consistency level documentation. Changes to the consistency level take effect immediately for all connections. |
| Global consistency timeout | How long (in ms) a read-only node waits for data to synchronize before the timeout policy applies. Range: 1–1,000,000 ms. Default: 100 ms. Available only when the consistency level is Global Consistency (Strong). |
| Global consistency timeout policy | What happens when the synchronization wait exceeds the timeout. Options: Send requests to primary node (default), Return error messages due to timeout, or Automatic downgrade to inconsistent read due to timeout. Available only when the consistency level is Global Consistency (Strong). |
Choosing a consistency level
| Level | What a read query sees | Suitable for |
|---|---|---|
| Eventual Consistency (Weak) | Data as of the last replicated checkpoint. A query does not wait for in-flight writes to propagate — it may return slightly stale data. | Workloads that tolerate brief stale reads: product catalog, leaderboards, analytics |
| Session Consistency (Medium) | All committed writes made in the same session. Queries wait if needed to reflect that session's own committed writes. | Workloads where a user must immediately see their own changes: profile updates, shopping cart |
| Global Consistency (Strong) | All committed writes across all sessions and nodes. Each query waits until the read-only node has fully caught up. | Workloads that require strict consistency across concurrent users: financial transactions, order processing |
Global Consistency (Strong) requires PolarDB for PostgreSQL or PolarDB for PostgreSQL (compatible with Oracle 2.0) with minor engine version 2.0.14.11.22.0 or later. For details, see Global consistency.
Connection pool settings
| Setting | Description |
|---|---|
| Connection pool | Select Off (default) or Transaction-level. Transaction-level connection pooling multiplexes physical database connections across application threads, reducing the number of concurrent connections to the database. Consider enabling it if your application frequently hits connection limits or uses serverless functions that open many short-lived connections. For details, see Transaction-level connection pooling. |
Modify a cluster endpoint
Log on to the PolarDB console. In the left navigation pane, click Clusters. Select the region of your cluster and click the cluster ID.
On the Basic Information page, go to the Database Connections section. Find the endpoint you want to modify and click Configure.
In the Modify Endpoint Settings dialog, update the parameters.
Click OK.
Read/write mode changes apply only to new connections. Consistency level changes take effect immediately for all connections.
Release a custom cluster endpoint
Releasing a custom cluster endpoint is permanent. The endpoint cannot be recovered. Update your application's connection strings immediately after releasing.
Only custom cluster endpoints can be released. Default cluster endpoints cannot be released.
Log on to the PolarDB console. In the left navigation pane, click Clusters. Select the region of your cluster and click the cluster ID.
On the Basic Information page, go to the Database Connections section. Find the custom cluster endpoint you want to release and click Release.
In the confirmation dialog, click OK.
API operations
| API | Description |
|---|---|
| CreateDBClusterEndpoint | Create a custom cluster endpoint |
| DescribeDBClusterEndpoints | Query cluster endpoints |
| DeleteDBClusterEndpoint | Release a custom cluster endpoint |