Compare PolarDB Read Consistency Levels for Optimal Performance - PolarDB

PolarDB supports four consistency levels for read/write splitting: eventual consistency, session consistency, global consistency, and global consistency (high-performance mode). Each level trades read latency for data freshness — higher consistency means reads may wait longer for replication to catch up.

Choose a consistency level

Level	Read waits?	Primary node load	Recommended when
Eventual consistency	Never	Lowest	Stale reads are acceptable; maximize read-only node utilization
Session consistency	Only if needed within a session	Low	Most applications — guarantees read-your-writes within a session
Global consistency	Yes, per request	Higher	Cross-session dependencies, such as connection pool scenarios
Global consistency (high-performance mode)	No (kernel-level)	Minimal overhead	PolarDB for MySQL 5.7, 8.0.1, or 8.0.2 requiring strict strong consistency

Use session consistency for most workloads. It minimizes impact on cluster performance while covering the majority of consistency requirements. For PolarDB for MySQL 5.6, use global consistency instead, because high-performance mode is not supported on that version.

How PolarDB replicates data

PolarDB uses asynchronous physical replication to keep read-only nodes in sync with the primary node. After a write on the primary node completes, the changes propagate to read-only nodes — in most cases within a few milliseconds. This replication delay is the root cause of read inconsistencies in a read/write splitting setup.

Eventual consistency

Eventual consistency routes all reads to read-only nodes with no waiting. A SELECT immediately after a write may return stale data if the replication delay has not closed.

INSERT INTO t1(id, price) VALUES(111, 96);
UPDATE t1 SET price = 100 WHERE id=111;
SELECT price FROM t1;  -- May return 96 instead of 100 if replication has not caught up

Use eventual consistency when you want to maximize read-only node utilization and your application can tolerate reading slightly stale data.

Session consistency

Session consistency, also known as causal consistency, guarantees read-your-writes within a session. After any write, subsequent reads in the same session always see that write's results — even if they are routed to a read-only node.

How it works

PolarProxy tracks the log sequence number (LSN) applied on each node. Each write records its LSN as the session LSN. When a read arrives, PolarProxy routes it only to nodes where the applied LSN is greater than or equal to the session LSN. If the LSN on a read-only node is smaller than the session LSN, PolarProxy forwards the request to that node only when the node updates to the latest data within the specified timeout period.

Because PolarDB uses physical replication, catch-up is fast. While a read-only node returns results to the client, replication to other nodes continues in parallel, allowing data to be updated on read-only nodes before subsequent read requests arrive.

Use session consistency for most applications. It preserves the benefits of read/write splitting and load balancing while ensuring consistent results within each session.

Global consistency

Session consistency covers dependencies within a single session. It does not cover cross-session dependencies — for example, when a connection pool assigns the same logical thread to different database connections across requests. In that case, a write in one session may not be visible to a read in a different session.

Global consistency solves this by checking the primary node's latest LSN before every read request. PolarProxy batches multiple concurrent read requests together to fetch the primary LSN in bulk, minimizing overhead. Once at least one read-only node's LSN reaches the primary LSN (LSN0), PolarProxy routes the read to that node. This guarantees that every read reflects all committed writes up to the moment the request was initiated.

Configuration parameters

Parameter	Display name	Description	Valid values	Default
`ConsistTimeout`	Global Consistency Timeout	Maximum time PolarProxy waits for a read-only node to reach the primary LSN after receiving a read request.	0–60000	20 (milliseconds)
`ConsistTimeoutAction`	Global Consistency Timeout Policy	Action taken when `ConsistTimeout` expires. `0`: route the read to the primary node. `1`: return the error `wait replication complete timeout, please retry`.	0, 1	0

To modify these parameters, see Configure PolarProxy.

Use global consistency for scenarios in which a large number of read requests and a small number of write requests are processed, such as connection pool scenarios with cross-session read-after-write dependencies. If replication delay is high, some reads may fall back to the primary node, increasing its load.

Global consistency (high-performance mode)

Global consistency (high-performance mode) provides strong consistency — a higher guarantee than global consistency — implemented at the kernel level by PolarTrans. It uses Commit Timestamp Store (CTS) and Remote Direct Memory Access (RDMA) to ensure that all reads from any read-only node in the cluster return strongly consistent results, without the per-request wait overhead of standard global consistency.

For limitations, how it works, how to enable it, and performance benchmarks, see Global consistency (high-performance mode).

Force a query to the primary node

Use the /*FORCE_MASTER*/ hint to send a specific query directly to the primary node, regardless of the configured consistency level:

/*FORCE_MASTER*/ SELECT * FROM user;

Hints have the highest routing priority — they override consistency levels and transaction splitting.

Usage notes:

When running this statement from the MySQL command-line client, add the -c flag, or the client strips the hint comment. For details, see mysql client options.
Hints cannot contain SQL statements that change environment variables. For example, if you use /*FORCE_SLAVE*/ SET NAMES utf8;, errors may occur.
Evaluate the impact on your workload before using hints in production, as they bypass all load-balancing logic.

Set the consistency level

Eventual consistency, session consistency, or global consistency: Configure the level in PolarProxy settings. See Configure PolarProxy.
Global consistency (high-performance mode): See Enable global consistency (high-performance mode).

PolarDB:Consistency levels