Update comment for ReplicationSlot.last_saved_restart_lsn

akorotkov · amitkapila · akorotkov · commit 0810fbb02dbe · 2025-07-21T15:07:54.000+03:00
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
@@ -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;
 
