In PolarDB's one-writer, multi-reader architecture, read-only nodes default to session consistency: a session can always read its own writes, but different sessions — and different services — may read stale data from read-only nodes. Global consistency removes this limitation by ensuring every read-only node always returns the most recent data committed on the primary node, across all sessions and services.
When to use global consistency
Enable global consistency when your application routes reads to read-only nodes and requires that different services can read each other's latest writes.
A typical scenario: Service A writes a value and notifies Service B through a message queue. Without global consistency, Service B may read a stale value from a read-only node — even though Service A already committed the update. In latency-sensitive industries such as finance and gaming, this stale-read window can cause business logic failures.
Without global consistency, the only way to guarantee cross-service read-after-write consistency is to route all reads to the primary node, leaving read-only nodes underutilized.
If all reads originate within the same database session, session consistency is sufficient and you do not need to enable global consistency.
How it works
PolarDB implements global consistency using Commit Sequence Numbers (CSNs). Each read-write transaction committed on the primary node receives a CSN, which records the commit order and replaces the active transaction list used in standard PostgreSQL. The primary node writes CSNs to the Write-Ahead Log (WAL), giving read-only nodes a complete, ordered view of transaction state through WAL replay.
When a client sends a query to a read-only node:
The read-only node fetches the current largest CSN from the primary node over the network.
The read-only node builds a consistent read view using that CSN and waits for its local WAL replay to catch up to the corresponding transaction state.
The read-only node determines data visibility based on the read view and returns the result to the client.
Prerequisites
Before enabling global consistency, verify that your cluster runs:
PolarDB for PostgreSQL (Compatible with Oracle) 2.0, revision version 2.0.14.22.0 or later
Run the following statement to check the revision version:
SHOW polar_version;To upgrade, see Upgrade the version.
Enable global consistency
Step 1: Enable CSN parameters
Log on to the PolarDB console.
In the left-side navigation pane, click Clusters.
In the upper-left corner, select the region where the cluster is deployed.
Find the cluster and click its ID.
In the left-side navigation pane, choose Settings and Management > Parameters.
Set both
polar_csn_enableandpolar_global_csn_enabletoON.
You must restart the cluster to allow the modified parameter settings to take effect. Before you modify the parameters, make business arrangements and proceed with caution. For configuration steps, see .
Step 2: Set the cluster endpoint consistency level
On the Basic Information page of your cluster, scroll to the Database Connections section.
Click Configure next to Cluster Endpoint, or hover over the Cluster Endpoint card and click Modify.
In the Modify Endpoint Settings dialog box, set Consistency Level to Global Consistency (Strong).
Configure the timeout behavior:
Parameter Description Global Consistency Timeout Maximum time the system waits for a read-only node to catch up to the primary node. Range: 1–1,000,000 ms. Default: 100 ms. Global Consistency Timeout Policy Behavior when a read-only node cannot catch up within the timeout. Values: Send Requests to Primary Node (Default) — reroutes the read to the primary node; Return Error Messages Due to Timeout — returns an error to the client; Automatic Downgrade to Inconsistent Read Due to Timeout — serves the read from the current state without waiting. Click OK to save.
Disable global consistency for a specific session
After you enable global consistency at the cluster endpoint level, it applies to all new queries by default. To bypass global consistency for a specific session — for example, for batch queries that do not require strong consistency — run the following statement at the start of that session:
SET polar_scc_enable = off;This setting applies only to the current session. Other sessions are unaffected.
FAQ
The read latency is high in low-write scenarios. What should I do?
Log on to the PolarDB console and set the synchronous_commit parameter to ON to prevent read latency in low-write load scenarios. For configuration steps, see Configure cluster parameters.
What does the timeout error mean?
If a read-only node cannot replay WAL records up to the required CSN within the configured timeout, the client receives:
SCC timeout waiting for WAL replayThis typically happens during write-heavy periods when the read-only node falls behind. To address this:
Increase the timeout: If your cluster handles heavy or unpredictable write loads, set Global Consistency Timeout to a larger value. In the Modify Endpoint Settings dialog, modify the value of the Global Consistency Timeout parameter.
Downgrade on timeout: Set Global Consistency Timeout Policy to Automatic Downgrade to Inconsistent Read Due to Timeout. When a read times out, the system serves it from the current state and returns no error to the client. Use this option when occasional stale reads are acceptable.