Global Consistency for Strong Reads in PolarDB PostgreSQL Overview - PolarDB

PolarDB for PostgreSQL enforces strong consistency at the kernel level, ensuring that read requests sent to any node in a cluster always return the latest committed data.

Applicability

Global consistency is supported on the following versions of PolarDB for PostgreSQL:

PostgreSQL 16 (minor engine version 2.0.16.9.9.0 or later)
PostgreSQL 14 (minor engine version 2.0.14.11.22.0 or later)

To check the minor engine version, log in to the console or run SHOW polardb_version;. If the version does not meet the requirements, upgrade the minor engine version. For instructions, see View the minor engine version.

Background

By default, read-only nodes in PolarDB provide session consistency: a client that writes data and immediately reads it back within the same session sees the latest value, even when the request is routed to a read-only node. Reads from a different session or service, however, are not guaranteed to reflect the most recent write.

This gap creates a real problem in microservice architectures. After Service A writes a value and publishes an event through a message queue, Service B may read from a read-only node and still see the old data. Without global consistency, the only safe option is to route all reads to the RW node — leaving read-only node capacity idle and forcing applications to maintain two separate sets of database connections.

Global consistency eliminates this constraint by guaranteeing that every read-only node always returns the latest committed data, regardless of which session or service issues the request.

How it works

Every read-write transaction committed on the RW node is assigned a Commit Sequence Number (CSN). The CSN defines the global transaction commit order and replaces the active transaction list used in native PostgreSQL, enabling a more efficient snapshot mechanism. The RW node records each CSN in the Write-Ahead Log (WAL), and read-only nodes replay the WAL to reconstruct a complete transaction state.

When a client queries a read-only node under global consistency:

The read-only node fetches the latest CSN from the RW node over the network.
It builds a strong consistency read view based on that CSN and waits for WAL replay to reach the corresponding offset.
It evaluates data visibility using the strong consistency read view and returns the result to the client.

Enable global consistency

Prerequisites

Before you begin, ensure that you have:

A PolarDB for PostgreSQL cluster running a supported version (see Applicability)
Access to the PolarDB console

Enable the CSN feature

Log in to the PolarDB console.
In the left navigation pane, click Clusters.
In the upper-left corner, select the region where the cluster is deployed.
Click the target cluster ID.
In the left navigation pane, choose Settings and Management > Parameters.
Set both polar_csn_enable and polar_global_csn_enable to on.
Important
After saving, restart the cluster for the changes to take effect. Schedule the restart window in advance. For parameter configuration instructions, see .

Set the consistency level

On the cluster's Basic Information page, go to the Database Connections section and click Configure next to Cluster Endpoint (or click Settings in the dialog box).
On the endpoint configuration page, set Consistency Level to Global Consistency (Strong).

Configure the two related parameters:

Parameter	Description	Default
Global Consistency Timeout	How long a read-only node waits for WAL replay before applying the timeout policy. Valid values: 1–1,000,000. Unit: ms.	100
Global Consistency Timeout Policy	Action to take when a read-only node times out. See the table below.	0

Global Consistency Timeout Policy values:

Value	Behavior
0	0, Send Requests to Primary Node (Default)
1	1, Return Error Messages Due to Timeout
2	2, Automatic Downgrade to Inconsistent Read Due to Timeout

FAQ

How do I disable global consistency for a specific session?

After global consistency is enabled on a cluster endpoint, it applies to all new connections. To opt out for a single session, run:

SET polar_scc_enable = off;

How do I adjust the global consistency timeout?

In the PolarDB console, click Configure next to the target cluster endpoint (or Settings in the dialog box) and update the Global Consistency Timeout value.

When a timeout occurs, the client receives:

SCC timeout waiting for WAL replay

For clusters with heavy or unstable write workloads, increase Global Consistency Timeout to reduce the frequency of timeouts.

How do I avoid read latency in low write-load scenarios?

In low write-load scenarios, read-only nodes may wait for WAL replay even when there is no new data. To reduce this latency, set the synchronous_commit parameter to on in the PolarDB console. For instructions, see Set cluster parameters.

How do I automatically downgrade consistency after a timeout?

In the PolarDB console, click Configure next to the target cluster endpoint (or Settings in the dialog box), then set Global Consistency Timeout Policy to 2, Automatic Downgrade to Inconsistent Read Due to Timeout. When a timeout occurs, the query proceeds with an inconsistent read and no error is returned to the client.