PolarDB:Physical and logical replication: Read WAL logs from the WAL buffer

Supported versions

This feature is available for the following PolarDB for PostgreSQL minor engine versions:

To check your minor engine version, run SHOW polardb_version; or view the minor engine version in the console. If the version doesn't meet the requirement, upgrade the minor engine version.

How it works

PostgreSQL supports two replication modes:

• Physical replication: synchronizes data between primary and standby nodes by transferring WAL log content.

• Logical replication: synchronizes data between publisher and subscriber nodes by transferring logical changes decoded from WAL logs.

A running instance can have multiple physical and logical replication links at the same time. Each link has a dedicated WAL sender process that reads WAL logs from storage, parses them, and sends them downstream over the network. Because each link's replication progress is independent, every process reads the full set of WAL logs from storage on its own.

When there are many replication links, WAL log read bandwidth can be several times higher than write bandwidth, consuming many input/output operations per second (IOPS). Under high I/O pressure, this WAL read I/O interferes with regular business read/write I/O, slowing business operations and increasing replication latency.

WAL logs are first written to the WAL buffer before a background process flushes them to storage. The WAL buffer space is reused cyclically, so it always holds the most recent WAL logs — exactly the logs that replication processes need most.

Without this feature, each replication process reads WAL logs from storage even when those logs are still present in the WAL buffer, generating redundant disk I/O. With this feature enabled, replication processes read WAL logs directly from the WAL buffer whenever the logs are present — even if those logs have already been written to disk. This converts read I/O into memory copy operations, significantly reducing read I/O amplification and lowering both WAL read latency and overall replication latency.

Enable WAL buffer reads for replication

The polar_enable_read_from_wal_buffers parameter controls this feature. It is enabled by default (on), so all replication processes benefit without any configuration changes.

To explicitly enable or disable the feature, set the parameter in your cluster configuration. For instructions, see .

Monitor WAL buffer hit statistics

Use the polar_monitor extension to check how often replication processes are reading from the WAL buffer instead of from storage.

1. Create the polar_monitor extension.

   CREATE EXTENSION IF NOT EXISTS polar_monitor;

2. Query WAL buffer hit statistics.

   SELECT * FROM polar_stat_walsnd_xlog_read();

   The output is similar to:

   pid   | hit  | hit_bytes | prefetched | prefetched_bytes | read | read_bytes
   ---------+------+-----------+------------+------------------+------+------------
    3865685 | 2175 | 251583064 |          0 |                0 |   82 |   10628128
    3865751 | 2173 | 251582792 |          0 |                0 |   82 |   10628400
   (2 rows)

   Each row corresponds to one replication process. A high hit count relative to read indicates that most WAL reads are served from the buffer, confirming the feature is working effectively. The following table describes the returned fields.

   Column	Data type	Description
   pid	INTEGER	Process ID (PID) of the replication process
   hit	BIGINT	Number of read I/O operations that hit the WAL buffer directly
   hit_bytes	BIGINT	Bytes read by I/O operations that hit the WAL buffer directly
   prefetched	BIGINT	Number of read I/O operations that hit the memory cache after WAL logs were prefetched from storage in batches
   prefetched_bytes	BIGINT	Bytes read by I/O operations that hit the memory cache after WAL logs are prefetched from storage in batches
   read	BIGINT	Number of read I/O operations that read WAL logs from storage
   read_bytes	BIGINT	Bytes of WAL logs read from storage