All Products
Search

This Product

    PolarDB:CreateDBClusterEndpointZonal

    Document Center

    PolarDB:CreateDBClusterEndpointZonal

    Last Updated:Sep 24, 2026

    Creates a custom cluster endpoint for a PolarDB on ENS cluster.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    polardb:CreateDBClusterEndpointZonal

    create

    *All Resource

    *

    		 None None

    Request syntax

    GET  HTTP/1.1

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    DBClusterId

    string

    Yes

    The cluster ID.

    pc-***************
    EndpointType

    string

    Yes

    The type of the custom cluster endpoint. Set the value to Custom.

    Custom
    Nodes

    string

    No

    The read load nodes to add to the endpoint. Separate multiple nodes with commas (,). By default, all nodes are included.

    pi-**************,pi-*************
    ReadWriteMode

    string

    No

    The read/write mode. Valid values:

    • ReadWrite: read/write (automatic read/write splitting).

    • ReadOnly (default): read-only.

    ReadOnly
    AutoAddNewNodes

    string

    No

    Specifies whether new nodes are automatically added to this endpoint. Valid values:

    • Enable: New nodes are automatically added to this endpoint.

    • Disable (default): New nodes are not automatically added to this endpoint.

    Valid values:

    • Enable :

      New nodes are automatically added to this endpoint.

    • Disable :

      New nodes are not automatically added to this endpoint.

    Disable
    EndpointConfig

    string

    No

    The advanced configurations of the cluster endpoint in JSON format. You can configure the consistency level, transaction splitting, offload reads from primary node, and connection pool settings.

    • Configure the load balancing policy. Format: {"LoadBalancePolicy":"Load balancing policy"}. Valid values:

      • 0: connection-based load balancing (default).

      • 1: active-request-based load balancing.

    • Configure the consistency level. Format: {"ConsistLevel":"Consistency level"}. Valid values:

      • 0: eventual consistency.

      • 1: session consistency (default).

      • 2: global consistency.

    • Configure transaction splitting. Format: {"DistributedTransaction":"Transaction splitting"}. Valid values:

      • on: enables transaction splitting (default).

      • off: disables transaction splitting.

    • Configure whether the primary node accepts read requests. Format: {"MasterAcceptReads":"Offload reads from primary node"}. Valid values:

      • on: the primary node accepts read requests.

      • off: the primary node does not accept read requests (default).

    • Configure the connection pool. Format: {"ConnectionPersist":"Connection pool"}. Valid values:

      • off: disables the connection pool (default).

      • Session: enables the session-level connection pool.

      • Transaction: enables the transaction-level connection pooling.

    • Configure parallel query. Format: {"MaxParallelDegree":"Parallel query"}. Valid values:

      • A specific degree of parallelism. Example: "MaxParallelDegree":"2".

      • off: disables parallel query (default).

    • Configure automatic request distribution among row store and column store nodes. Format: {"EnableHtapImci":"Automatic request distribution among row store and column store"}. Valid values:

      • on: enables automatic request distribution among row store and column store nodes.

      • off: disables automatic request distribution among row store and column store nodes (default).

    • Configure whether to enable overload protection. Format: {"EnableOverloadThrottle":"Enable overload protection"}. Valid values:

      • on: enables overload protection.

      • off: disables overload protection (default).

    Note

    • Transaction splitting, offload reads from primary node, connection pool, and overload protection can be configured only when the read/write mode of the PolarDB for MySQL cluster endpoint is set to read/write (automatic read/write splitting).

    • When the read/write mode of the PolarDB for MySQL cluster endpoint is read-only, both connection-based load balancing and active-request-based load balancing are supported. When the read/write mode is read/write (automatic read/write splitting), only active-request-based load balancing is supported.

    • Automatic request distribution among row store and column store nodes can be configured when the read/write mode of the PolarDB for MySQL cluster endpoint is read/write (automatic read/write splitting), or when the read/write mode is read-only and the load balancing policy is active-request-based load balancing.

    • Only PolarDB for MySQL supports setting the consistency level to global consistency.

    • If the ReadWriteMode parameter is set to ReadOnly, the consistency level can only be set to 0.

    • You can configure the consistency level, transaction splitting, offload reads from primary node, and connection pool at the same time. Example: {"ConsistLevel":"1","DistributedTransaction":"on","ConnectionPersist":"Session","MasterAcceptReads":"on"}.

    • The transaction splitting setting is constrained by the consistency level. For example, when the consistency level is set to 0, transaction splitting cannot be enabled. When the consistency level is set to 1 or 2, transaction splitting can be enabled.

    {"ConsistLevel": "1","DistributedTransaction": "on"}
    ClientToken

    string

    No

    The client token that is used to ensure the idempotence of the request and prevent repeated submissions. The token is generated by the client, must be unique across requests, is case-sensitive, and cannot exceed 64 ASCII characters in length.

    6000170000591aed949d0f******************
    DBEndpointDescription

    string

    No

    The name of the custom cluster endpoint.

    test
    SccMode

    string

    No

    Specifies whether to enable global consistency (high-performance mode) for the node. Valid values:

    • ON: Enabled.

    • OFF: Disabled.

    Valid values:

    • off :

      Disabled.

    • on :

      Enabled.

    on
    PolarSccWaitTimeout

    string

    No

    The timeout period for global consistency.

    100
    PolarSccTimeoutAction

    string

    No

    The timeout policy for global consistency. Valid values:

    • 0: Sends the request to the primary node.

    • 2: Timeout degradation. When a global consistency read times out, the query is automatically degraded to regular requests, and the client does not receive an error message.

    0

    Response elements

    Element

    Type

    Description

    Example

    object

    Schema of Response

    RequestId

    string

    The request ID.

    CD35F3-F3-44CA-AFFF-BAF869******

    Examples

    Success response

    JSON format

    {
  "RequestId": "CD35F3-F3-44CA-AFFF-BAF869******"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 ClusterEndpoint.StatusNotValid Cluster endpoint status is not valid. The state of the cluster endpoint is invalid.
    400 EndpointNum.Error Endpoint number error. The maximum number of endpoints is exceeded.
    400 LockTimeout The request processing has failed due to lock timeout. Failed to process the request due to a lock timeout.
    403 OperationDenied.InstanceType The operation is not permitted due to instance type. The operation is not allowed due to the instance type
    404 EndpointConfig.Invalid Endpoint config is invalid. The advanced parameter of the cluster endpoint is invalid.
    404 InvalidDBClusterId.NotFound The DBClusterId provided does not exist in our records. The specified DBClusterId parameter does not exist in the current record.
    404 EndpointConfig.Conflict Endpoint config is invalid, CausalConsistRead should be session since node SCC mode enabled. Endpoint the configuration is invalid, the CausalConsistRead should be a session because global consistency (high performance mode) for the node is enabled.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.