When client drivers such as Java Database Connectivity (JDBC) wrap all requests in transactions by default, PolarProxy routes every request to the primary node — leaving read-only nodes underutilized. Transaction splitting fixes this by routing reads that occur before the first write in a transaction to read-only nodes, reducing load on the primary node without any changes to your application code.
How it works
By default, when using a PolarDB cluster endpoint in read/write mode, PolarProxy sends all requests within a transaction to the primary node to preserve read/write consistency. This becomes a bottleneck when drivers like JDBC automatically wrap requests in transactions.
With transaction splitting enabled, PolarProxy splits reads and writes within a transaction:
Read requests received before the first write request in a transaction are routed to read-only nodes.
Once a write request is issued, all subsequent read and write requests in that transaction go to the primary node.
This split happens transparently — no changes to application code or database configuration are needed.
Because read-only nodes cannot serve uncommitted data, routing reads to them before any write ensures data consistency within the transaction.
Routing conditions
A read request is routed to a read-only node only when all of the following conditions are met:
The transaction uses the Read Committed isolation level.
The read request arrives before the first write request in the transaction.
The consistency level is set to eventual consistency, or the read-only nodes have already synchronized all data from the primary node.
When routing does not apply: If the consistency level is not set to eventual consistency and the read-only nodes have not yet caught up with the primary node, PolarProxy routes the read request to the primary node instead.
Consistency levels and routing behavior
The consistency level setting directly affects whether reads are routed to read-only nodes:
| Consistency level | Routing behavior |
|---|---|
| Eventual consistency | Reads before the first write are immediately routed to read-only nodes. |
| Other levels | Reads before the first write are routed to read-only nodes only after those nodes have fully synchronized with the primary node. If not yet synchronized, reads go to the primary node. |
For information about configuring consistency levels, see Configure PolarProxy.
Enable transaction splitting
Enable transaction splitting when configuring a custom cluster endpoint. For details, see Configure PolarProxy.
This feature allows you to transfer read loads from the primary node to read-only nodes without modifying application code or configurations, making the primary node more stable.
API reference
| API | Description |
|---|---|
| Modifies cluster endpoint attributes, including read/write mode, consistency level, transaction splitting, and offload reads from primary node settings. You can also specify whether to associate the specified cluster endpoint with newly added nodes. |