All Products
Search
Document Center

PolarDB:ModifyDBClusterEndpoint

Last Updated:Mar 01, 2024

Modifies the attributes of a PolarDB cluster endpoint, such as the read/write mode, the consistency level, transaction splitting, and connection pool. You can also specify whether newly added nodes are automatically associated with a specified cluster endpoint and whether the primary node handles read requests.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
polardb:ModifyDBClusterEndpointWRITE
  • dbcluster
    acs:polardb:{#regionId}:{#accountId}:dbcluster/{#dbclusterId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DBClusterIdstringYes

The ID of the cluster.

pc-*************
DBEndpointIdstringYes

The ID of the endpoint.

pe-**************
NodesstringNo

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. 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 Oracle clusters: One of the selected nodes must be the primary node.
pi-**************,pi-*************
ReadWriteModestringNo

The read/write mode. Valid values:

  • ReadWrite: The cluster endpoint handles read and write requests. Automatic read/write splitting is enabled.
  • ReadOnly: The cluster endpoint handles read-only requests.
ReadWrite
AutoAddNewNodesstringNo

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

  • Enable
  • Disable
Enable
EndpointConfigstringNo

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 the read /write mode of a PolarDB for MySQL cluster is set to Read-only, the Connection-based SLB and Active Request-based SLB SLB policies are supported. The Read-write (Automatic read /write splitting) mode of the cluster supports Active Request-based SLB policy.

  • 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.

{"ConsistLevel":"1","DistributedTransaction":"on","MasterAcceptReads":"off","ConnectionPersist": "on"}
DBEndpointDescriptionstringNo

The name of the custom cluster endpoint.

test

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The ID of the request.

CD3FA5F3-FAF3-44CA-AFFF-BAF869******

Examples

Sample success responses

JSONformat

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

Error codes

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

For a list of error codes, visit the Service error codes.

Change history

Change timeSummary of changesOperation
2023-09-12The Error code has changedsee changesets
Change itemChange content
Error CodesThe Error code has changed.
    Error Codes 400 change
    Error Codes 404 change