From bc72772ee016743187ee5e7276012aaea3ea02e7 Mon Sep 17 00:00:00 2001
From: Ashutosh Sharma <ashu.coek88@gmail.com>
Date: Wed, 10 Jun 2026 16:47:03 +0000
Subject: [PATCH] doc: clarify pg_stat_replication view for logical replication

Update the pg_stat_replication documentation to cover logical
replication alongside physical replication.

The view now mentions logical subscribers in addition to standbys,
and a new paragraph explains the differing semantics of the LSN
columns depending on replication type:

- For physical replication, the LSN columns reflect WAL sending,
  writing, flushing, and replay on the standby as before.
- For logical replication, sent_lsn reflects publisher-side decoding
  progress, not delivery to the subscriber. write_lsn, flush_lsn,
  and replay_lsn reflect subscriber-reported progress via replication
  status messages, and do not guarantee that changes have been
  received, durably stored, or applied on the subscriber side.
---
 doc/src/sgml/monitoring.sgml | 50 ++++++++++++++++++++++++++----------
 1 file changed, 37 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 08d5b824552..92190634e71 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -323,7 +323,7 @@ postgres   27093  0.0  0.0  30096  2752 ?        Ss   11:34   0:00 postgres: ser
      <row>
       <entry><structname>pg_stat_replication</structname><indexterm><primary>pg_stat_replication</primary></indexterm></entry>
       <entry>One row per WAL sender process, showing statistics about
-       replication to that sender's connected standby server.
+       replication to that sender's directly connected client.
        See <link linkend="monitoring-pg-stat-replication-view">
        <structname>pg_stat_replication</structname></link> for details.
       </entry>
@@ -1212,11 +1212,29 @@ description | Waiting for a newly initialized WAL file to reach durable storage
    <primary>pg_stat_replication</primary>
   </indexterm>
 
-   <para>
-   The <structname>pg_stat_replication</structname> view will contain one row
-   per WAL sender process, showing statistics about replication to that
-   sender's connected standby server.  Only directly connected standbys are
-   listed; no information is available about downstream standby servers.
+  <para>
+  The <structname>pg_stat_replication</structname> view will contain one row
+  per WAL sender process, showing statistics about replication to that
+  sender's directly connected client.  For physical replication, the client
+  is a standby server.  For logical replication, the client is a logical
+  replication client, such as a subscriber apply worker.  No information is
+  available about downstream replication nodes.
+  </para>
+
+  <para>
+  For physical replication, the LSN columns in this view describe the
+  positions up to which WAL has been sent, written, flushed, and replayed
+  on the connected standby server.  For logical replication,
+  <structfield>sent_lsn</structfield> reflects the LSN up to which the
+  walsender has processed WAL records.  Such records may already have been
+  streamed to the subscriber, queued for streaming at transaction commit, or
+  skipped because they were not eligible for logical decoding.
+
+  <structfield>write_lsn</structfield>, <structfield>flush_lsn</structfield>,
+  and <structfield>replay_lsn</structfield> reflect progress reported by the
+  subscriber through replication status messages, and do not necessarily
+  mean that logical changes up to those LSNs have already been
+  received, durably stored, or made visible on the subscriber.
   </para>
 
   <table id="pg-stat-replication-view" xreflabel="pg_stat_replication">
@@ -1371,7 +1389,9 @@ description | Waiting for a newly initialized WAL file to reach durable storage
        <structfield>sent_lsn</structfield> <type>pg_lsn</type>
       </para>
       <para>
-       Last write-ahead log location sent on this connection
+         For physical replication, the last write-ahead log location sent on
+         this connection.  For logical replication, the last write-ahead log
+        location processed by this walsender.
       </para></entry>
      </row>
 
@@ -1380,8 +1400,9 @@ description | Waiting for a newly initialized WAL file to reach durable storage
        <structfield>write_lsn</structfield> <type>pg_lsn</type>
       </para>
       <para>
-       Last write-ahead log location written to disk by this standby
-       server
+         For physical replication, the last write-ahead log location written
+        to disk by this standby server.  For logical replication, progress
+        reported by the subscriber through replication status messages.
       </para></entry>
      </row>
 
@@ -1390,8 +1411,9 @@ description | Waiting for a newly initialized WAL file to reach durable storage
        <structfield>flush_lsn</structfield> <type>pg_lsn</type>
       </para>
       <para>
-       Last write-ahead log location flushed to disk by this standby
-       server
+         For physical replication, the last write-ahead log location flushed
+        to disk by this standby server.  For logical replication, progress
+        reported by the subscriber through replication status messages.
       </para></entry>
      </row>
 
@@ -1400,8 +1422,10 @@ description | Waiting for a newly initialized WAL file to reach durable storage
        <structfield>replay_lsn</structfield> <type>pg_lsn</type>
       </para>
       <para>
-       Last write-ahead log location replayed into the database on this
-       standby server
+         For physical replication, the last write-ahead log location replayed
+        into the database on this standby server.  For logical replication,
+        progress reported by the subscriber through replication status
+        messages.
       </para></entry>
      </row>
 
-- 
2.43.0