pg_stat_replication docs incomplete for logical replication

From: Ashutosh Sharma <ashu(dot)coek88(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: pg_stat_replication docs incomplete for logical replication
Date: 2026-06-11 05:07:56
Message-ID: CAE9k0Pn+grZ9cgiKdAB-h_AQBD_8Zsob2gD=p3aDV=e2g2Odrw@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi,

I noticed that the documentation for the pg_stat_replication view does
not adequately cover logical replication. The current text only
mentions standby servers, leaving the behaviour of the LSN columns
undefined and potentially misleading for users of logical replication.

Specifically:

1. The view description refers only to "connected standby servers",
omitting logical subscribers, which also appear as rows in the view.

2. The LSN columns (sent_lsn, write_lsn, flush_lsn, replay_lsn) have
fundamentally different semantics for logical replication compared to
physical replication, but this is not documented anywhere.

The distinction matters because:

- sent_lsn for logical replication reflects publisher-side decoding
and output progress, not how far data has been delivered to the
subscriber.
- write_lsn, flush_lsn, and replay_lsn reflect progress reported by
the subscriber through replication status messages, and do not
guarantee that committed changes have been received, durably stored,
or made visible on the subscriber.

This can lead users to incorrectly assume that LSN values in this view
confirm end-to-end delivery of changes in a logical replication setup.

Proposed correction:

- Update the view description to mention logical subscribers alongside standbys.
- Add a paragraph clarifying the differing semantics of the LSN
columns for physical vs logical replication.

I have a patch ready for review if the approach looks acceptable.
Please have a look and let me know your thoughts.

--
With Regards,
Ashutosh Sharma.

Attachment Content-Type Size
0001-doc-clarify-pg_stat_replication-view-for-logical-rep.patch application/octet-stream 5.8 KB

Browse pgsql-hackers by date

  From Date Subject
Next Message Dilip Kumar 2026-06-11 05:13:51 Re: Proposal: Conflict log history table for Logical Replication
Previous Message Henson Choi 2026-06-11 05:05:42 Re: Row pattern recognition