Creates a custom cluster endpoint for a specified PolarDB cluster.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String No CreateDBClusterEndpoint

The operation that you want to perform. Set the value to CreateDBClusterEndpoint.

DBClusterId String Yes pc-**************

The ID of the PolarDB cluster.
EndpointType String Yes Custom

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

Nodes String No pi-**********,pi-*********

The reader nodes to be associated with the endpoint. If you need to specify multiple reader nodes, separate the reader nodes with commas (,). By default, all the nodes in the specified cluster are associated with the cluster endpoint.

Note
  • You must specify the node ID for each PolarDB for MySQL cluster.
  • You must specify the role name of each node for each PolarDB for PostgreSQL or PolarDB-O cluster. The valid values of role names include Writer, Reader1, and Reader2.
  • If you set ReadWriteMode to ReadOnly, only one node can be associated with the cluster endpoint. If the only node becomes faulty, the cluster endpoint may be unavailable for up to an hour. We recommend that you do not associate only one node with the cluster endpoint in production environments. We recommend that you associate at least two nodes with the cluster endpoint to improve service availability.
  • If you set ReadWriteMode to ReadWrite, you must associate at least two nodes with the cluster endpoint.
    • No limits are imposed on the two nodes that you select for each PolarDB for MySQL cluster. If the two nodes are read-only nodes, write requests are forwarded to the primary node.
    • The following limit applies to PolarDB for PostgreSQL and PolarDB-O clusters: One of the selected nodes must be the primary node.
ReadWriteMode String No ReadOnly

The read/write mode. Valid values:

  • ReadWrite: receives and forwards read and write requests. Automatic read/write splitting is enabled.

  • ReadOnly: receives and forwards only read requests.

    Default value: ReadOnly
AutoAddNewNodes String No Disable

Specifies whether to automatically associate newly added nodes with the cluster endpoint. Valid values:

  • Enable: Newly added nodes are automatically associated with the cluster endpoint.
  • Disable: Newly added nodes are not automatically associated with the cluster endpoint.

Default value: Disable
EndpointConfig String No {"ConsistLevel": "1","DistributedTransaction": "on"}

The advanced configurations of the cluster endpoint. You must specify the configurations in the JSON format. You can specify the configurations of the following attributes: consistency level, transaction splitting, connection pool, and offload reads from the primary node.

  • Specify the consistency level in the format of {\"ConsistLevel\":\"Consistency level\"}. Valid values:
    • 0: eventual consistency.
    • 1: session consistency. The value 1 is the default value.
    • 2: global consistency.
  • Specify the transaction splitting feature in the format of {\"DistributedTransaction\":\"Transaction splitting\"}. Valid values:
    • on: enables the transaction splitting feature. By default, the feature is enabled.
    • off: disables the transaction splitting feature.
  • Specify the offload reads from the primary node feature in the format of {\"MasterAcceptReads\":\"Offload reads from the primary node\"}. Valid values:
    • on: The primary node accepts read requests.
    • off: The primary node does not accept read requests. The value off is the default value.
  • Specify the connection pool in the format of {\"ConnectionPersist\":\"Connection pool\"}. Valid values:
    • off: disables the connection pool. By default, the connection pool is disabled.
    • Session: enables the session-level connection pool.
    • Transaction: enables the transaction-level connection pool.
Note
  • You can specify the transaction splitting, connection pool, and offload reads from the primary node features for a PolarDB for MySQL cluster only if ReadWriteMode is set to ReadWrite for the cluster endpoint.
  • Only PolarDB for MySQL supports global consistency.
  • If the ReadWriteMode parameter is set to ReadOnly, the value for the consistency level must be 0.
  • You can use one record to specify the consistency level, transaction splitting, connection pool, and offload reads from the primary node features, such as {\"ConsistLevel\":\"1\",\"DistributedTransaction\":\"on\",\"ConnectionPersist\":\"Session\",\"MasterAcceptReads\":\"on\"}.
  • The setting of the transaction splitting feature is affected by the specified consistency level. For example, if you set the consistency level to 0, transaction splitting cannot be enabled. If you set the consistency level to 1 or 2, transaction splitting can be enabled.
ClientToken String No 6000170000591aed949d0f******************

The client token that is used to ensure the idempotency of requests. If an API operation is idempotent, the API operation returns the same result for identical requests. You can use the client to generate the value. Make sure that the value is unique for different requests. The token is case-sensitive. The token can contain only ASCII characters and cannot exceed 64 characters in length.

DBEndpointDescription String No test

The name of the custom cluster endpoint.

Response parameters

Parameter Type Example Description
RequestId String CD35F3-F3-44CA-AFFF-BAF869******

The ID of the request.

Examples

Sample requests

http(s)://polardb.aliyuncs.com/? Action=CreateDBClusterEndpoint
&DBClusterId=pc-**************
&EndpointType=Custom
&<Common request parameters>

Sample success responses

XML format 

<CreateDBClusterEndpointResponse>
  <RequestId>CD35F3-F3-44CA-AFFF-BAF869******</RequestId>
</CreateDBClusterEndpointResponse>

JSON format 

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

Error codes

For a list of error codes, visit the API Error Center.