Modifies the attributes of a specified PolarDB cluster endpoint. For example, you can modify the following attributes for the specified cluster endpoint: read/write mode, consistency level, transaction splitting, primary node accepts read requests, and connection pool. You can also call the operation to specify whether newly added nodes are automatically associated with the specified cluster endpoint.

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

ParameterTypeRequiredExampleDescription
ActionStringYesModifyDBClusterEndpoint

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

DBClusterIdStringYespc-*************

The ID of the cluster.

DBEndpointIdStringYespe-**************

The ID of the endpoint.

NodesStringNopi-**************,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, the predefined 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 PostgreSQL(Compatible with 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.
ReadWriteModeStringNoReadWrite

The read/write mode. Valid values:

  • ReadWrite: The cluster endpoint receives and forwards read and write requests. Automatic read/write splitting is enabled.
  • ReadOnly: read-only permissions
AutoAddNewNodesStringNoEnable

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

  • Enable
  • Disable
EndpointConfigStringNo{"ConsistLevel":"1","DistributedTransaction":"on","MasterAcceptReads":"off","ConnectionPersist": "on"}

The advanced configurations of the cluster endpoint, which are in the JSON format. You can specify the configurations of the following attributes: consistency level, transaction splitting, connection pool, and primary node accepts read requests.

  • Specifies the load balancing policy in the format of {\"LoadBalancePolicy\":\"Selected value\"}. Default value: 0. Valid values:
    • 0: connections-based load balancing
    • 1: active requests-based load balancing
  • Specifies whether to enable the primary node accepts read requests feature in the format of {\"MasterAcceptReads\":\"Selected value\"}. Default value: on. Valid values:
    • on
    • off
  • Specifies whether to enable the transaction splitting feature in the format of {\"DistributedTransaction\":\"Selected value\"}. Default value: on. Valid values:
    • on
    • off
  • Specifies the consistency level in the format of {\"ConsistLevel\":\"Selected value\"}. Default value: 1. Valid values:
    • 0: eventual consistency (weak)
    • 1: session consistency (medium)
    • 2: global consistency (strong)
  • Specifies the connection pool in the format of {\"ConnectionPersist\":\"Selected value\"}. Default value: off. Valid values:
    • off: disables the connection pool.
    • Session: enables the session-level connection pool.
    • Transaction: enables the transaction-level connection pool.
  • Specifies whether to enable the parallel query feature in the format of {\"MaxParallelDegree\":\"Selected value\"}. Default value: off. Valid values:
    • on
    • off
  • Specifies whether to enable the automatic request distribution between row store and column store nodes feature in the format of {\"EnableHtapImci\":\"Selected value\"}. Default value: off. Valid values:
    • on
    • off
  • Specifies whether to enable the overload protection feature in the format of {\"EnableOverloadThrottle\":\"Selected value\"}. Default value: off. Valid values:
    • on
    • off
Note
  • You can specify the transaction splitting, primary node accepts read requests, connection pool, and overload protection features for a PolarDB for MySQL cluster only if ReadWriteMode is set to ReadWrite for the cluster endpoint.
  • If ReadWriteMode is set to ReadOnly for the cluster endpoint of a PolarDB for MySQL cluster, both connections-based load balancing and active requests-based load balancing are supported. If ReadWriteMode is set to ReadWrite, only active requests-based load balancing is supported.
  • If ReadWriteMode is set to ReadWrite for the cluster endpoint of a PolarDB for MySQL cluster or if ReadWriteMode is set to ReadOnly and the load balancing policy is set to active requests-based load balancing, the automatic request distribution between row store and column store nodes feature is supported.
  • Only PolarDB for MySQL supports global consistency.
  • If the ReadWriteMode parameter is set to ReadOnly, the consistency level must be 0.
  • You can specify the consistency level, transaction splitting, connection pool, and primary node accepts read requests features at a time, 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.
DBEndpointDescriptionStringNotest

The name of the endpoint.

Response parameters

ParameterTypeExampleDescription
RequestIdStringCD3FA5F3-FAF3-44CA-AFFF-BAF869******

The ID of the request.

Examples

Sample requests

http(s)://polardb.aliyuncs.com/?Action=ModifyDBClusterEndpoint
&DBClusterId=pc-*************
&DBEndpointId=pe-**************
&Nodes=pi-**************,pi-*************
&ReadWriteMode=ReadWrite
&AutoAddNewNodes=Enable
&EndpointConfig={"ConsistLevel":"1","DistributedTransaction":"on","MasterAcceptReads":"off","ConnectionPersist": "on"}
&DBEndpointDescription=test
&<Common request parameters>

Sample success responses

XML format

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

<ModifyDBClusterEndpointResponse>
    <RequestId>CD3FA5F3-FAF3-44CA-AFFF-BAF869******</RequestId>
</ModifyDBClusterEndpointResponse>

JSON format

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

{
  "RequestId" : "CD3FA5F3-FAF3-44CA-AFFF-BAF869******"
}

Error codes

Http status codeError codeError messageDescription
400InvalidEndpointConfig.MalformedThe specified parameter EndpointConfig is not valid.The error message returned because the specified EndpointConfig parameter is invalid.
400InvalidDBEndpointId.MalformedThe specified parameter DBEndpointId is not valid.The error message returned because the specified DBEndpointId parameter is invalid.
404InvalidDBCluster.NotFoundThe DBClusterId provided does not exist in our records.The error message returned because the specified DBClusterId does not exist.
404EndpointStatus.NotSupportCurrent endpoint status does not support this operation.The error message returned because this operation is not supported while the node is in the current state.

For a list of error codes, see Service error codes.