Global consistency-PolarDB(PolarDB)-阿里云帮助中心

Overview

PolarDB for PostgreSQL and provide a global consistency feature at the database kernel level that ensures that read requests sent to any node in a cluster return strongly consistent results.

Applicability

This feature is supported on the following versions of PolarDB for PostgreSQL:

PostgreSQL 14 (minor engine version 2.0.14.11.22.0 or later).

Note

You can view the minor engine version in the console or by running the SHOW polardb_version; statement. If your cluster's minor engine version does not meet the requirements, upgrade the minor engine version.

Background

In the original PolarDB one-writer, multi-reader architecture, read-only nodes provide session consistency by default. Although physical replication and shared storage can effectively reduce replication lag on read-only nodes, they cannot guarantee that read requests will retrieve the latest data written to the read-write node. In latency-sensitive industries such as finance and gaming, this read lag can cause business logic inconsistencies.

As shown in the figure, business applications are often decoupled using a microservices framework. After Service A writes data, it sends a write-success message to Service B through a message queue. In a session-consistent scenario, if Service A immediately reads the data within the same session after updating col to 20, it receives the latest result of 20, even if the request is routed to a read-only node. However, after being notified of the update, if Service B reads directly from a read-only node, it might still retrieve the old value of 10. This scenario can cause data consistency issues for the application. To ensure read-after-write consistency, applications must forward read requests to the read-write node, which leaves read-only node resources idle.

How it works

PolarDB for PostgreSQL and provide a strong consistency read capability for read-only nodes at the database kernel level, which ensures that read-only nodes always see the latest data written to the read-write node. This capability provides cluster-wide strong consistency for read operations. When global consistency is enabled, every read-write transaction committed on the read-write node is assigned a commit sequence number (CSN). The CSN represents the transaction commit order and is used to build more efficient transaction snapshots, replacing the native PostgreSQL active transaction list. The read-write node records the CSN in the write-ahead log (WAL), and read-only nodes replay the WAL to construct a complete transaction state.

The following steps describe the SQL execution process for a strong consistency read on an RO node:

A client sends a query request to a read-only node.
The read-only node retrieves the latest CSN from the read-write node over the network.
The read-only node uses the latest CSN from the read-write node to build a strong consistency read view and waits for its transaction state to replay to that point.
The read-only node determines data visibility based on this view and returns the result to the client.

Procedure

Log on to the PolarDB console. In the left-side navigation pane, click Clusters. Select the region where your cluster is located, and then click the cluster ID.
In the left-side navigation pane, choose Settings and Management > Parameters. Set the polar_csn_enable and polar_global_csn_enable parameters to on to enable the transaction CSN feature.

Note
These parameter modifications require a cluster restart to take effect. Plan accordingly. For more information about how to set cluster parameters in the console, see Set cluster parameters.
On the Basic Information page, in the Database Connections section, click Configure next to Cluster Endpoint (Recommended), or click Modify in the dialog box that appears.

On the Edit Endpoint page, set the consistency level to Global Consistency (Strong) and configure the two related parameters:

Parameter

Description

Global Consistency Timeout

The maximum time, in milliseconds, that a read-only node waits to synchronize with the primary node. Valid values: 1 to 1,000,000. Default: 100.

Global Consistency Timeout Policy

The action to take when a read-only node times out. Valid values:

Send Requests to Primary Node (Default)
Return Error Messages Due to Timeout
Automatic Downgrade to Inconsistent Read Due to Timeout

FAQ

Disabling for a session

After global consistency is enabled on a read-only node, it applies to all new connections by default. If specific queries do not require this feature, run the following command to disable global consistency for the current session:

SET polar_scc_enable = off;

Read timeout

Log on to the PolarDB console. Click Configure next to the cluster endpoint or Modify in the dialog box that opens. Then, modify the Global Consistency Timeout. If a timeout occurs, the client receives the following error message:

SCC timeout waiting for WAL replay

Note

For clusters with heavy or unstable write loads, consider setting a larger value for the Global Consistency Timeout.

Timeout downgrade policy

Log on to the PolarDB console. Click Configure next to the cluster endpoint or Modify in the dialog box that appears. Set the Global Consistency Timeout Policy to Automatic Downgrade to Inconsistent Read Due to Timeout. When a global consistency read times out, the query operation automatically downgrades to an inconsistent read, and the client does not receive an error message. For the valid values and more details about this parameter, see the description of the Global Consistency Timeout Policy parameter.

Avoiding read latency

Log on to the PolarDB console and set the synchronous_commit parameter to on to avoid read latency in low-write-load scenarios. For more information about how to modify parameters in the console, see Set cluster parameters.