12. Logical Replication on Hironobu SUZUKI @ InterDB

12.1. Overview

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

This section introduces key concepts that are necessary to understand the descriptions in the subsequent sections.

Section Contents

In logical replication, four types of processes work cooperatively:

A walsender on the Publisher mainly sends WAL data to the Subscriber, and does some various jobs.
A logical replication launcher on the Subscriber launches apply workers.
An apply worker on the Subscriber establishes a connection with the publisher’s walsender, receives the stream of logical changes, parses these messages, and updates the target tables accordingly.
A table sync worker on the Subscriber performs the initial data synchronization for a specific table, catching up to the main replication stream before handing over further updates to the apply worker. Refer to Section 12.2.2 for details.

12.1.2. Outline of Logical Replication

PostgreSQL’s logical replication is inherently row-based. It captures changes to individual rows and streams them in a decoded format, ensuring consistency even when using non-deterministic functions, while remaining independent of the physical storage layout.

12.2. Starting Logical Replication

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

Before setting up logical replication, we assume the following:

The Publisher has the tables that will be replicated to the Subscriber.
The Subscriber has already created tables with the same structure as those on the Publisher, but without any data.

In this section, we use the following tables:

CREATE TABLE tbl_1 (id int PRIMARY KEY, name text, data int);
CREATE TABLE tbl_2 (id int NOT NULL UNIQUE, name text, data int);
CREATE INDEX tbl_2_idx on tbl_2 (id, name);
CREATE TABLE tbl_3 (id int, name text, data int);
ALTER TABLE tbl_3 REPLICA IDENTITY FULL;

To set up logical replication, two commands are issued:

12.3. ReorderBuffer Structure

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

A ReorderBuffer area is allocated for each walsender process. The size of this area is limited by the logical_decoding_work_mem configuration parameter (the default is 64MB).

The ReorderBuffer consists of the following three components:

Figure 12.11. ReorderBuffer Structure.

The central element of the ReorderBuffer structure is the by_txn hash table, which uses the transaction ID (txid) as its key. Each entry in this hash table is a ReorderBufferTXN structure, which stores metadata and the actual WAL data associated with each transaction.

12.4. WAL Data Filtering and Buffering

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

This section describes the data filtering and buffering mechanism within the ReorderBuffer.

The discussion begins with the multi-stage filtering process executed by the walsender, which determines which records are eligible for decoding. This is followed by a practical demonstration of how the ReorderBuffer accumulates these changes through a concrete transaction scenario.

Furthermore, it explains the differences in WAL data storage for UPDATE and DELETE statements based on the Replica Identity.

12.5. Logical Decoding Output Plugins: pgoutput

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

The primary role of an output plugin is to serialize the change data—which has been organized and reordered by the ReorderBuffer — into a format compatible with sending to a subscriber.

The specific tasks performed by the plugin include:

Data Transformation and Filtering: The plugin performs a final validation of the binary data within the ReorderBuffer against the publication’s configuration. It determines whether the target table or specific actions (e.g., INSERT, TRUNCATE) are included in the subscription and evaluates row filters or column lists. Once irrelevant data is excluded, the plugin formats the remaining payload into the appropriate data types and structures (e.g., text or binary) dictated by the replication protocol.
Message Generation: The plugin constructs a logical sequence of messages, such as BEGIN, INSERT/UPDATE/DELETE/TRUNCATE, and COMMIT. These messages are passed to the walsender process, which manages the network sending.

As the name implies, this mechanism is pluggable. Custom plugins can be implemented to support unique output formats or specialized internal processing logic. In standard PostgreSQL logical replication, the officially supported pgoutput is used as the default plugin.

12.6. Transaction Reassembly and Sending Message

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

This section describes how the ReorderBuffer reassembles accumulated changes and performs the sending process to the subscriber’s apply worker via an output plugin.

Section Contents

12.6.1. Outline of Transaction Reassembly

When the walsender detects a COMMIT record in the WAL, the ReorderBuffer initiates the reassembly process. It organizes the captured changes in LSN order and passes them to the output plugin. After the plugin completes the processing of the transaction, the ReorderBuffer releases the associated memory by deleting the change records and the ReorderBufferTXN entry.

12.7. Apply Worker and Transaction Replay

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

The apply worker is the core component responsible for replaying logical changes received from the publisher onto the subscriber’s local tables.

This section first reviews the fundamental operation of the apply worker, followed by an analysis of advanced modes involving the incremental processing of large transactions and the coordinated use of parallel apply workers.

Section Contents

12.7.1. Process Overview (streaming = off)

The apply worker on the subscriber node performs the following primary tasks:

12.8. Internal Mechanism of Restart and Crash Recovery

Mon, 01 Jan 0001 00:00:00 +0000

Alpha Version: Work in progress.

This section provides an overview of Write-Ahead Log (WAL) data management in logical replication. Based on these fundamentals, it then details the sequences for subscriber restarts and crash recovery.

Section Contents

12.8.1. WAL Data Management

Replication progress is managed based on the Log Sequence Number (LSN) of WAL data.

Unlike streaming replication, where the primary and standby share the exact same WAL space, logical replication requires a mapping between the publisher’s and subscriber’s WAL spaces, as each utilizes its own independent LSN.

12. Logical Replication on Hironobu SUZUKI @ InterDB

12.1. Overview

Alpha Version: Work in progress.

12.1.1. Related Processes

12.1.2. Outline of Logical Replication

12.2. Starting Logical Replication

Alpha Version: Work in progress.

12.3. ReorderBuffer Structure

Alpha Version: Work in progress.

Figure 12.11. ReorderBuffer Structure.

12.4. WAL Data Filtering and Buffering

Alpha Version: Work in progress.

12.5. Logical Decoding Output Plugins: pgoutput

Alpha Version: Work in progress.

12.6. Transaction Reassembly and Sending Message

Alpha Version: Work in progress.

12.6.1. Outline of Transaction Reassembly

12.7. Apply Worker and Transaction Replay

Alpha Version: Work in progress.

12.7.1. Process Overview (streaming = off)

12.8. Internal Mechanism of Restart and Crash Recovery

Alpha Version: Work in progress.

12.8.1. WAL Data Management