From 8222e8a7a7312de75359464e6fc2baad16e29974 Mon Sep 17 00:00:00 2001
From: Ashutosh Sharma <ashu.coek88@gmail.com>
Date: Tue, 16 Jun 2026 10:40:24 +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.

Author: Ashutosh Sharma <ashu.coek88@gmail.com>
Reviewed-by: Peter Smith <smithpb2250@gmail.com>
---
 doc/src/sgml/monitoring.sgml | 51 +++++++++++++++++++++++++++---------
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 08d5b824552..ca88f0d44ba 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,30 @@ 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.
+  </para>
+  <para>
+    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 +1390,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 +1401,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 is
+       reported by replication status messages received from the subscriber.
       </para></entry>
      </row>
 
@@ -1390,8 +1412,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 is
+       reported by replication status messages received from the subscriber.
       </para></entry>
      </row>
 
@@ -1400,8 +1423,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 is reported by replication status messages received from the
+       subscriber.
       </para></entry>
      </row>
 
-- 
2.43.0