PolarProxy serves as a proxy between the database and the application in a PolarDB cluster. It receives and routes all requests from the application. PolarProxy supports advanced features, such as read/write splitting, transaction splitting, and connection pool. PolarProxy is easy to use and maintain, and provides high-availability and high-performance services. You can connect to PolarDB cluster endpoints to use the features of PolarProxy.

PolarDB architecture and PolarProxy introduction

1

A PolarDB cluster of Cluster Edition consists of a primary node and one or more read-only nodes. By default, PolarDB provides two types of endpoints: the primary endpoint and cluster endpoints. PolarDB PolarProxy provides cluster endpoints. Cluster endpoints include read/write endpoints and read-only endpoints. Read/write endpoints support read/writing splitting. For more information, see Read/write splitting. Read-only endpoints enable PolarDB clusters to distribute read requests to read-only nodes based on the number of connections.

Limits

Only PolarDB clusters of Cluster Edition support cluster endpoints and PolarProxy. PolarDB clusters of the Single node and Archive database editions use a single-node architecture, and do not support cluster endpoints and PolarProxy.

Considerations

  • If you do not enable the transaction splitting feature after cluster endpoints are used, all requests in a transaction are forwarded to the primary node.
  • When you execute the SHOW PROCESSLIST statement after cluster endpoints are used, the system returns the results of all nodes.
  • If you execute multi-statements or call stored procedures, all subsequent requests for the current connection are forwarded to the primary node. For more information, see Multi-Statement. To use the read/write splitting feature, you must close the current connection and reconnect to the cluster.
  • The maximum number of connections to a PolarDB cluster endpoint depends on the specifications of compute nodes in backend databases.
  • If a session that supports read/write splitting is created after you add or restart a read-only node, read requests are forwarded to the read-only node. If a session that supports read/write splitting is created before you add or restart a read-only node, read requests are not forwarded to the read-only node. To forward these read requests to the read-only node, you must close the connection and reconnect to the cluster. For example, you can restart your application to establish a new connection.
  • Do not modify environment variables when you call stored procedures or execute multi-statements, such as set names utf8mb4;select * from t1;. Otherwise, data inconsistency occurs when read requests are sent to read-only nodes and the primary node.

Read/write splitting

PolarDB clusters of Cluster Edition support read/write splitting. This feature enables a PolarDB cluster to distribute read and write requests from applications by using a cluster endpoint. Write requests are forwarded to the primary node. Read requests are forwarded to the primary node or read-only nodes based on the loads of each node. The number of pending requests on a node indicates the loads on the node. For more information, see Read/write splitting.

Transaction splitting

PolarDB supports transaction splitting. This feature ensures data consistency in a session and allows PolarDB to send read requests to read-only nodes. This reduces the loads on the primary node. For more information, see Transaction splitting.

Connection Pool

PolarDB supports session-level connection pools and transaction-level connection pools. You can select a connection pool based on your business requirements to reduce the database loads caused by a large number of connections. For more information, see Connection pool.

Parallel query

The parallel query feature is a parallel query framework that is released in PolarDB for MySQL 8.0. PolarDB enables the framework based on database costs and rules. For more information, see Parallel query.

Custom cluster endpoints

PolarDB allows you to create custom cluster endpoints. You can set the read/write mode for custom cluster endpoints and add specific nodes to meet your business requirements. This improves service flexibility. For more information, see Custom cluster endpoint.

FAQ

  • Why am I unable to retrieve a record immediately after I insert the record?

    In a read/write splitting architecture, replication latency may occur during data replication between the primary node and read-only nodes. However, PolarDB supports session consistency. This allows you to query the updates within a session. Therefore, you can retrieve the inserted record after the data replication is completed.

  • Why do read-only nodes have no loads?

    By default, requests in transactions are forwarded to only the primary node. If you use Sysbench for stress testing, you can add --oltp-skip-trx=on to your code for Sysbench 0.5 or add --skip-trx=on to your code for Sysbench 1.0. This skips BEGIN and COMMIT statements. If a large number of transactions cause low loads on read-only nodes, you can submit a ticket to enable the transaction splitting feature.

  • Why does one node receive more requests than others?

    Requests are distributed to each node based on loads. The nodes with lower loads receive more requests.

  • Can I read data from PolarDB without latency?

    No, you cannot read data from PolarDB immediately after the data is written. A latency in milliseconds occurs when you read data by using an endpoint that has read/write splitting enabled. This latency exists even if the loads on the primary node and read-only nodes of a PolarDB cluster are not heavy. To read data without latency, you can connect to the primary endpoint and send read and write requests to the primary node of the PolarDB cluster.

  • Does a new read-only node automatically receive read requests?

    Yes, if a session that supports read/write splitting is created after you add a read-only node, read requests are automatically forwarded to the read-only node. However, if a session that supports read/write splitting is created before you add a read-only node, read requests are not forwarded to the read-only node. To forward these read requests to the read-only node, you must close the connection and reconnect to the cluster. For example, you can restart your application to establish a new connection.

Related operations

API Description
CreateDBEndpointAddress Creates a public endpoint for a specified PolarDB cluster.
CreateDBClusterEndpoint Creates a custom cluster endpoint for a specified PolarDB cluster.
DescribeDBClusterEndpoints Queries the information about the endpoints of a specified PolarDB cluster.
ModifyDBClusterEndpoint Modifies the configurations of a cluster endpoint for a specified PolarDB cluster.
ModifyDBEndpointAddress Changes the endpoints of a specified PolarDB cluster, such as a custom cluster endpoint.
DeleteDBEndpointAddress Deletes the public endpoint of a specified PolarDB cluster. The public endpoint can be the primary endpoint, the default cluster endpoint, or a custom cluster endpoint.
DeleteDBClusterEndpoint Deletes a custom cluster endpoint of a specified PolarDB cluster.