This topic answers frequently asked questions about PolarProxy in PolarDB, covering read/write splitting behavior and cluster endpoint operations.
Read/write splitting
Node routing at a glance
Understanding which node handles each operation type helps diagnose unexpected behavior:
| Operation | Routed to |
|---|---|
| Write requests | Primary node |
| Read requests (outside a transaction) | Read-only nodes (load-based) |
| Read requests (inside a transaction) | Primary node (default) |
| Read requests via primary endpoint | Primary node |
| Read requests via read/write splitting endpoint | Read-only nodes |
Why can't I read a record immediately after inserting it?
In a read/write splitting architecture, data replication from the primary node to read-only nodes is asynchronous, so a short delay occurs before a write becomes visible on a read-only node.
PolarDB addresses this with session consistency: within the same session, you can always read your own writes. The record becomes visible to other sessions after replication completes.
For details, see the "Session consistency" section in Consistency levels.
Can I read data immediately after writing it?
No. When reading through a read/write splitting endpoint, a delay of a few milliseconds applies even under light loads. This delay is caused by asynchronous replication — writes are confirmed on the primary node before the data propagates to read-only nodes.
To eliminate the delay, connect through the primary endpoint. All reads and writes then go directly to the primary node.
To find the primary endpoint, see View or apply for an endpoint.
Why are read-only nodes underloaded when the primary node is busy?
By default, all requests inside a transaction are routed to the primary node. If most of your workload runs inside transactions, read-only nodes receive little traffic.
Two options to redistribute the load:
Skip transactions in stress tests. When running Sysbench, add
--oltp-skip-trx=on(Sysbench 0.5) or--skip-trx=on(Sysbench 1.0) to avoid wrapping statements in BEGIN/COMMIT.Enable transaction splitting. This feature routes read statements out of transactions to read-only nodes, reducing load on the primary node. See Transaction splitting.
Why does one node receive more requests than the others?
PolarDB distributes requests based on current load — nodes with lighter loads receive more requests. Uneven distribution is expected behavior, not a misconfiguration.
Does a new read-only node automatically start receiving read requests?
It depends on when the session was created. Sessions established after you add the read-only node automatically route read requests to it. Sessions that were open before you added the node continue using the previous routing until they reconnect.
To start sending traffic to the new node immediately, close existing connections and reconnect — for example, by restarting your application.
Cluster endpoints
Can a read-only node with a single-node cluster endpoint become the primary node after failover?
Not automatically. After a failover, a read-only node that has a single-node cluster endpoint assigned does not take over as the primary node on its own. You can promote it manually if needed.
For the promotion procedure, see Automatic failover and manual failover.
Can I modify a cluster endpoint?
Yes. Both the default cluster endpoint and custom cluster endpoints can be modified. See Modify a custom cluster endpoint.
Can I delete a cluster endpoint?
You can delete custom cluster endpoints, but not the default cluster endpoint. See Release a custom cluster endpoint.