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;