Modifies the attributes of a PolarDB cluster endpoint. For example, you can modify the following attributes for a cluster endpoint: read/write mode, consistency level, transaction splitting, offload reads from the primary node, and connection pool. You can also call the operation to specify whether newly added nodes are automatically associated with a 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

Parameter Type Required Example Description
Action String No ModifyDBClusterEndpoint

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

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

The ID of the PolarDB for MySQL cluster.

DBEndpointId String Yes pe-**************

The ID of the cluster endpoint.

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, 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 Oracle 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 for Oracle clusters: One of the selected nodes must be the primary node.
ReadWriteMode String No ReadWrite

The read/write mode. Valid values:

  • ReadWrite: The cluster endpoint receives and forwards read and write requests. Automatic read/write splitting is enabled.
  • ReadOnly: The cluster endpoint only has read permissions on the database.
AutoAddNewNodes String No Enable

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

  • Enable: yes
  • Disable: no (default)
EndpointConfig String No {"ConsistLevel":"1","DistributedTransaction":"on","MasterAcceptReads":"off","ConnectionPersist": "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 MySQ 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.
DBEndpointDescription String No test

The name of the custom cluster endpoint.

Note This parameter takes effect for only custom cluster endpoints.

Response parameters

Parameter Type Example Description
RequestId String CD3FA5F3-FAF3-44CA-AFFF-BAF869******

The ID of the request.

Examples

Sample requests

http(s)://polardb.aliyuncs.com/?Action=ModifyDBClusterEndpoint
&DBClusterId=pc-*************
&DBEndpointId=pe-**************
&<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

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