CreateDBClusterEndpoint - PolarDB

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 parameter


Parameter	Type	Required	Example	Description
Action	String	Yes	CreateDBClusterEndpoint	The operation that you want to perform. The operation that you want to perform. Set the value to CreateDBClusterEndpoint.
DBClusterId	String	Yes	pc-**************	The ID of the 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 (,). If you do not specify this parameter, all nodes are used by default. 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 for Oracle cluster. Example: `Writer,Reader1,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 for PostgreSQL(Compatible with Oracle) 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: The account has the read-only permissions on the database. 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"}`. Default value: 1. Valid values: 0: eventual consistency. 1: session consistency. 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 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 transaction splitting settings are restricted by the consistency level settings. 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 idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can only contain ASCII characters and cannot exceed 64 characters in length. The token is case-sensitive.
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 response

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "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 error message returned because the status of the cluster endpoint is invalid.
400	EndpointNum.Error	Endpoint number error.	The error message returned because the endpoint number is invalid.
404	EndpointConfig.Invalid	Endpoint config is invalid.	The error message returned because the advanced configurations of the cluster endpoint are invalid.
404	InvalidDBClusterId.NotFound	The DBClusterId provided does not exist in our records.	The error message returned because the specified DBClusterId does not exist in the current record.
404	EndpointConfig.Conflict	Endpoint config is invalid, CausalConsistRead should be session since node SCC mode enabled.	The error message returned because the endpoint configurations are invalid. CausalConsistRead must be a session because the SCC mode is enabled on the node.

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