When you use a cluster endpoint in read/write mode, some database client drivers — such as the Java Database Connectivity (JDBC) driver — wrap every request in a transaction automatically. This means all traffic, including read-only queries, goes to the primary node. Read-only nodes sit idle, the primary node handles unnecessary load, and you need no additional code changes to fix this.
Transaction splitting lets PolarProxy route read requests within a transaction to read-only nodes, redistributing load without requiring any changes to your application code. This feature can also be used to ensure read/write consistency.
How it works
By default, PolarProxy sends all requests in a session to the primary node when you use a cluster endpoint in read/write mode. Because drivers like JDBC wrap all requests in transactions, even read-only queries hit the primary node regardless of whether they involve writes.
With basic transaction splitting enabled, PolarProxy splits reads from writes within each transaction:
Read requests received before the first write request in a transaction are forwarded to read-only nodes.
Once the first write request arrives, all subsequent requests — both reads and writes — are forwarded to the primary node to preserve data consistency.
Uncommitted data is never visible from read-only nodes.
When to use transaction splitting
Transaction splitting is most effective when:
Your application uses a cluster endpoint in read/write mode.
Your workload is predominantly read-heavy.
Reads are automatically wrapped in transactions by the driver — for example, JDBC applications with
autoCommit=false.
Transaction splitting provides no benefit if your application already routes reads to a read-only endpoint directly, or if your workload is predominantly write-heavy.
Limitations
Isolation level: Only transactions using the Read Committed isolation level can be split. Other isolation levels (such as Repeatable Read or Serializable) require the session to stay pinned to a single node to guarantee consistency guarantees that depend on a stable snapshot, so splitting is not possible.
Consistency level interaction: If the consistency level is not set to eventual consistency, PolarProxy sends pre-write reads to read-only nodes only after those nodes have fully synchronized data from the primary node. If the nodes are behind, PolarProxy falls back to sending reads to the primary node. For details, see .
Enable transaction splitting
Prerequisites
Before you begin, ensure that you have:
A PolarDB for PostgreSQL (Compatible with Oracle) cluster with at least one read-only node
A cluster endpoint configured in read/write mode
Procedure
Log on to the PolarDB console.
In the upper-left corner, select the region where your cluster is deployed.
Find the cluster and click its ID.
In the Cluster Endpoints section, click Modify.
Click On next to Transaction Splitting.
Transaction splitting takes effect on new connections only. To apply the change to existing connections, close them and reconnect.
Click OK.
API reference
| Operation | Description |
|---|---|
| ModifyDBClusterEndpoint | Modifies cluster endpoint attributes, including read/write mode, consistency level, transaction splitting, and whether to offload read requests from the primary node. You can also specify whether to associate the specified cluster endpoint with newly added nodes. |