As read traffic grows, a single primary node becomes a bottleneck. PolarDB for PostgreSQL clusters include built-in read/write splitting via PolarProxy: when you connect through a cluster endpoint configured in Read and Write (Automatic Read-write Splitting) mode, the cluster routes write requests to the primary node and read requests to read-only nodes automatically—no application changes required.
Use cases
High read volume: Offload analytics queries, reporting jobs, and search operations to read-only nodes, freeing the primary node for writes.
Elastic scaling: Add read-only nodes to increase read throughput without modifying your application or connection strings.
Consistent reads within a session: Guarantee that reads in the same session reflect the latest writes, even when requests are spread across nodes.
How routing works
PolarProxy intercepts all traffic through the cluster endpoint and routes each request based on its type:
| Request type | Routed to |
|---|---|
| Write statements (INSERT, UPDATE, DELETE, DDL) | Primary node |
| Read statements (SELECT) | Read-only node |
| Statements inside a transaction | Primary node |
| Functions with write or mixed operations | Primary node |
| Read-only functions, including customized read-only functions | Read-only node |
| PREPARE statements with write operations + related EXECUTE | Primary node only |
| PREPARE statements with read-only operations | Broadcast to all nodes; EXECUTE routed by load |
Because PolarProxy runs as a native cluster component rather than an external proxy, it adds less latency than third-party middleware solutions.
Session-level read consistency
Within a session, PolarProxy selects a node based on each node's data synchronization progress, ensuring reads always reflect the latest committed writes. Load balancing resumes across nodes as the session continues.
Node health checks
PolarProxy continuously monitors all nodes. If a node fails or its latency exceeds the configured threshold, PolarProxy stops distributing read requests to that node and redistributes write and read requests to healthy nodes. The cluster remains accessible even if a read-only node goes down. When the node recovers, PolarProxy automatically adds it back to the routing pool.
Override routing with SQL hints
Add /*FORCE_MASTER*/ or /*FORCE_SLAVE*/ immediately before an SQL statement to override the default routing:
-- Default: routed to a read-only node
SELECT * FROM test;
-- Force to primary node
/*FORCE_MASTER*/ SELECT * FROM test;
-- Force to a read-only node
/*FORCE_SLAVE*/ SELECT * FROM test;Limitations
Unsupported connection method:
Connecting via the replication-mode method is not supported through the cluster endpoint. To set up a dual-node cluster based on a primary/secondary replication architecture, use the primary node endpoint directly.
Temporary resources created by functions:
Querying a temporary table created inside a function may return an error stating the table does not exist.
If a function contains a PREPARE statement, executing the related EXECUTE statement may return an error stating the PREPARE statement name does not exist.
Unsupported syntax:
Using a temporary table name to declare the %ROWTYPE attribute is not supported. For example:
CREATE TEMP TABLE fullname (first text, last text);
SELECT '(Joe,von Blow)'::fullname, '(Joe,d''Blow)'::fullname;Transaction routing:
All statements inside a transaction are routed to the primary node. Load balancing resumes after the transaction ends.
Configure a cluster endpoint
To create a custom cluster endpoint, see Configure PolarProxy.
To modify an existing cluster endpoint, see Configure PolarProxy.
After the cluster endpoint is created, configure it in your application to enable automatic read/write splitting. No other application-side changes are needed.
Next steps
Transaction splitting — control how transactions are split across nodes
Consistency levels — configure the consistency guarantee for your workload
API reference
| API | Description |
|---|---|
| CreateDBEndpointAddress | Creates a public-facing endpoint for a PolarDB cluster |
| DescribeDBClusterEndpoints | Queries endpoint information for a PolarDB cluster |
| ModifyDBClusterEndpoint | Modifies the configuration of a cluster endpoint |
| ModifyDBEndpointAddress | Modifies an endpoint for a PolarDB cluster |
| DeleteDBEndpointAddress | Releases the public-facing endpoint of the primary endpoint, the default cluster endpoint, or a custom cluster endpoint for a PolarDB cluster |