How to configure a database proxy using a PolarDB cluster endpoint - PolarDB

This topic describes how to configure a database proxy using a PolarDB cluster endpoint.

Prerequisites

The cluster must be a PolarDB for MySQL Cluster Edition cluster. For more information about product editions, see Enterprise Edition.

Notes

Only PolarDB for MySQL 8.0 clusters support enabling parallel query and setting the degree of parallelism when you configure a database proxy.

Procedure

Log on to the PolarDB console. In the navigation pane on the left, click Clusters. Select the region where the cluster is located, and then click the ID of the target cluster to go to the cluster details page.
On the Basic Information page of the cluster, find the target cluster endpoint in the Database Connection section. Click Configure next to the endpoint name.

In the dialog box that appears, modify the configurations of the cluster endpoint as needed. The following table describes the configuration items.

Table 1. Configurations

Configuration item		Description
Network Information		PolarDB provides a private endpoint for each cluster endpoint by default. To modify the endpoint or apply for a public endpoint, see Manage endpoints.
Cluster Settings	Read/Write	The read/write mode of the cluster endpoint. Valid values are Read-only and Read/Write (Automatic Read/Write Splitting). Note You can change the read/write mode after you create a custom endpoint. The change takes effect only for new connections. Existing connections retain their original mode.
Cluster Settings	Endpoint Name	Enter a name for the cluster endpoint.
Node Settings	Available Nodes and Selected Nodes	From the Available Nodes box on the left, which includes the primary node and all read-only nodes, select the nodes that you want to add to the cluster endpoint to process read requests. Click the icon to move them to the Selected Nodes box on the right. Note The node selection does not affect the read/write mode: If the read/write mode is set to Read/Write (Automatic Read/Write Splitting), write requests are sent only to the primary node, regardless of whether the primary node is in the Selected Nodes box. If the read/write mode is set to Read-only, all read requests are forwarded to the read-only nodes based on the load balancing policy and are not forwarded to the primary node. This applies even if the primary node is in the Selected Nodes box. If the read/write mode is set to Read/Write (Automatic Read/Write Splitting), because Multi-master Cluster (Limitless) Edition uses a database and table routing mechanism, you must add the primary node of the destination database and table to the read/write endpoint, or select all primary nodes. Evaluate the routing impact before you select nodes.
Node Settings	Automatically Associate New Nodes	Specifies whether to automatically add new nodes to this endpoint.
Load Balancing Settings	Load Balancing Policy	The scheduling policy used to process read requests among multiple nodes when read/write splitting is enabled. Valid values are Connections-based Load Balancing and Active Request-based Load Balancing. For more information about load balancing policies, see Load balancing policy.
	Primary Node Accepts Read Requests	Select No. Query SQL statements are sent only to read-only nodes. This reduces the load on the primary node and ensures its stability. Select Yes. Query SQL statements can be sent to the primary node and read-only nodes. For more information about whether the primary node accepts read requests, see Primary node accepts read requests. Note This configuration is supported only in Read/Write (Automatic Read/Write Splitting) mode.
	Transaction Splitting	Enable or disable transaction splitting. For more information about transaction splitting, see Transaction splitting. Note This configuration is supported only in Read/Write (Automatic Read/Write Splitting) mode.
	On-demand Connection Establishment	Enable or disable the on-demand connection establishment feature. For more information about on-demand connection establishment, see On-demand Connection Establishment. Note This configuration is supported only when Load Balancing Policy is set to Active Request-based Load Balancing.
Consistency Settings	Consistency Level	If the read/write mode is Read/Write (Automatic Read/Write Splitting), you can set the consistency level to Eventual Consistency (Weak), Session Consistency (Medium), or Global Consistency (Strong). For more information, see Consistency level. If the read/write mode is Read-only, the consistency level is Eventual Consistency (Weak) and cannot be changed. Important A change to the consistency level immediately takes effect for all connections. Global consistency (high-performance mode) must take effect on all endpoints in the cluster at the same time. If you select a consistency level other than global consistency (high-performance mode), all other endpoints in the cluster will revert to the consistency state they were in before global consistency (high-performance mode) was enabled.
	Global Consistency Timeout	The timeout period for a read-only node to wait for the latest data to be synchronized. The value ranges from 0 to 60000. The default value is 20. The unit is ms. Note This configuration is supported only when Consistency Level is set to Global Consistency (Strong) and Global Consistency Mode is set to Traditional Mode.
	Global Consistency Timeout Policy	The default policy that PolarDB uses after a read-only node waits for a timeout. Valid values are: Send Requests to Primary Node (Default) SQL Exception: Wait replication complete timeout, please retry. Note This configuration is supported only when Consistency Level is set to Global Consistency (Strong) and Global Consistency Mode is set to Traditional Mode.
	Global Consistency Read Timeout (High-performance Mode)	The timeout period for a read-only node to wait for the latest data to be synchronized. The value ranges from 1 to 1000000. The default value is 100. The unit is ms. Important Global consistency (high-performance mode) must take effect on all endpoints in the cluster at the same time. If you enable global consistency (high-performance mode) for one endpoint, it is enabled for all other endpoints in the cluster. This configuration is supported only when Consistency Level is set to Global Consistency (Strong) and Global Consistency Mode is set to High-performance Mode.
	Global Consistency Read Timeout Policy (High-performance Mode)	The default policy that PolarDB uses after a read-only node waits for a timeout. Valid values are: 0, send the request to the primary node (default) 1, report a timeout error and return an error message to the client 2, downgrade on timeout. If a global consistency read times out, the query is automatically downgraded to a regular request, and no error message is returned to the client Note This configuration is supported only when Consistency Level is set to Global Consistency (Strong) and Global Consistency Mode is set to High-performance Mode.
	Session Consistency Read Timeout	The timeout period for a read-only node to wait for the latest data to be synchronized. The value ranges from 0 to 60000. The default value is 0. The unit is ms. Important This configuration is supported only when Consistency Level is set to Session Consistency (Medium). Global consistency (high-performance mode) must take effect on all endpoints in the cluster at the same time. If you select a consistency level other than global consistency (high-performance mode), all other endpoints in the cluster will revert to the consistency state they were in before global consistency (high-performance mode) was enabled.
	Session Consistency Read Timeout Policy	The default policy that PolarDB uses after a read-only node waits for a timeout. Valid values are: 0, send the request to the primary node (default) 1, report an SQL error (wait replication complete timeout, please retry) Note This configuration is supported only when Consistency Level is set to Session Consistency (Medium).
Connection Pool Settings	Connection Pool	You can select Off (default), Session-level, or Transaction-level. For more information about connection pools, see Connection pool. Note This configuration is supported only in Read/Write (Automatic Read/Write Splitting) mode. A change to the connection pool configuration takes effect only for new connections. Typically, you need to restart your application or rebuild the database connections for the change to take effect.
HTAP Optimization	Parallel Query	Enable or disable the parallel query feature and set the degree of parallelism. Enabling elastic parallel query (ePQ) lets you use the parallel processing capabilities of multi-core CPUs (idle compute resources in the cluster) to accelerate complex queries. For more information, see Elastic parallel query. Note Since April 1, 2023, elastic parallel query is enabled by default with a degree of parallelism of 2 if the cluster meets the following conditions: For a new cluster: The cluster has 8 or more CPU cores. For an existing cluster: You create a custom cluster endpoint for an existing cluster that has 8 or more CPU cores.
	Transactional/Analytical Processing Splitting	Enable or disable automatic request distribution between row and column stores. For more information, see Configure automatic request distribution between row store and column store nodes. Note This configuration is supported only for endpoints of PolarDB for MySQL 8.0.1 clusters with minor engine version 8.0.1.1.22 or later. The endpoint must be in Read/Write (Automatic Read/Write Splitting) mode, and the Selected Nodes in the Node Settings section must include at least one read-only column store node.
	Column Store Node Accepts OLTP Requests	Enable or disable the ability of column store nodes to accept OLTP requests. After you enable this feature, column store nodes will accept both OLAP and OLTP requests. The database proxy will route OLTP read requests to column store nodes based on the number of active requests. This may increase the load on the column store nodes. Note This configuration is supported only when Transactional/Analytical Processing Splitting is enabled.
Security Protection	Overload Protection	Enable or disable the overload protection feature. For more information, see Overload protection.

Click OK.

FAQ

Why do connection errors occur after I set the weight of a read-only node in a cluster endpoint to 0 and then remove the node?

Scenario: You need to remove a read-only node from a cluster endpoint. To avoid affecting connections to the node, you first set the read/write splitting weight of the read-only node to 0. You expect that subsequent read requests will not be sent to this node. However, after you remove the node from the cluster endpoint, connection errors occur on the client.
Cause: A cluster endpoint has two Load Balancing Policy: Active Request-based Load Balancing and Connections-based Load Balancing:
- Active Request-based Load Balancing: After you reduce the weight of a read-only node to 0, subsequent requests are no longer routed to that node.
- Connections-based Load Balancing: Load balancing is performed only when a connection is established. If an existing connection is established with a read-only node, subsequent requests on that connection are always sent to that read-only node.
Solution:
1. Switch the Load Balancing Policy of the cluster endpoint to Active Request-based Load Balancing.
2. Set the read/write splitting weight of the target read-only node to 0.
3. Remove the read-only node.

Related API operations

API	Description
Query the endpoint information of a PolarDB cluster	Query cluster endpoints.
Modify the attributes of a PolarDB cluster endpoint	Modify a cluster endpoint.
Release a custom PolarDB cluster endpoint	Release a custom cluster endpoint.