Update comment for ReplicationSlot.last_saved_restart_lsn

Document that restart_lsn can go backwards and explain why this could happen.

Discussion: https://postgr.es/m/1d12d2-67235980-35-19a406a0%4063439497
Discussion: https://postgr.es/m/CAPpHfdvuyMrUg0Vs5jPfwLOo1M9B-GP5j_My9URnBX0B%3DnrHKw%40mail.gmail.com
Author: Hayato Kuroda <kuroda.hayato@fujitsu.com>
Co-authored-by: Amit Kapila <amit.kapila16@gmail.com>
Reviewed-by: Vignesh C <vignesh21@gmail.com>
Reviewed-by: Amit Kapila <amit.kapila16@gmail.com>
Reviewed-by: Alexander Korotkov <aekorotkov@gmail.com>

diff --git a/src/include/replication/slot.h b/src/include/replication/slot.h
index 76aeeb92242e9ba1680d6ea8fd7c673211603a0f..19b4e8b6a030efff41f5a8484e4830ea3b95328d 100644 (file)
--- a/src/include/replication/slot.h
+++ b/src/include/replication/slot.h
@@ -220,6 +220,25 @@ typedef struct ReplicationSlot
         * Latest restart_lsn that has been flushed to disk. For persistent slots
         * the flushed LSN should be taken into account when calculating the
         * oldest LSN for WAL segments removal.
+        *
+        * Do not assume that restart_lsn will always move forward, i.e., that the
+        * previously flushed restart_lsn is always behind data.restart_lsn. In
+        * streaming replication using a physical slot, the restart_lsn is updated
+        * based on the flushed WAL position reported by the walreceiver.
+        *
+        * This replication mode allows duplicate WAL records to be received and
+        * overwritten. If the walreceiver receives older WAL records and then
+        * reports them as flushed to the walsender, the restart_lsn may appear to
+        * move backward.
+        *
+        * This typically occurs at the beginning of replication. One reason is
+        * that streaming replication starts at the beginning of a segment, so, if
+        * restart_lsn is in the middle of a segment, it will be updated to an
+        * earlier LSN, see RequestXLogStreaming. Another reason is that the
+        * walreceiver chooses its startpoint based on the replayed LSN, so, if
+        * some records have been received but not yet applied, they will be
+        * received again and leads to updating the restart_lsn to an earlier
+        * position.
         */
        XLogRecPtr      last_saved_restart_lsn;