From ce65e9f5e674d85987fbe1743d39bd0637eeb7eb Mon Sep 17 00:00:00 2001
From: Zsolt Parragi <zsolt.parragi@percona.com>
Date: Mon, 31 Aug 2026 08:40:44 +0000
Subject: [PATCH v7 5/5] doc: Explain how offline and online checksum changes
 interact

The lockstep procedure for offline checksum changes in a replication
setup was documented without preconditions.  It is not sufficient on
its own: an offline change is recorded only in the control file and
has no ordering against WAL the node has not replayed yet, so a node
stopped before replaying an online state transition applies it on
restart and overrides the offline change.  The nodes then silently
diverge even though the change was applied to all of them while
stopped.

Document the two durability models next to each other in wal.sgml,
and extend the pg_checksums notes: require standbys to have replayed
all WAL of their upstream node before stopping them, show how to
check that, and recommend not mixing online and offline changes.
---
 doc/src/sgml/ref/pg_checksums.sgml | 25 ++++++++++++++++++++++---
 doc/src/sgml/wal.sgml              | 13 +++++++++++++
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml
index 000940e7cb7..b337950be3d 100644
--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -248,9 +248,28 @@ PostgreSQL documentation
    directory; the new state does not propagate over replication.  In a
    replication setup the same change must be applied to every node: stop all
    nodes, run <application>pg_checksums</application> on each of them, and
-   only then restart them.  Tools that copy relation file blocks directly
-   between nodes, such as <xref linkend="app-pgrewind"/>, likewise require
-   both nodes to be in the same data checksum state.
+   only then restart them.  Before stopping a standby, make sure it has
+   replayed all WAL of its upstream node, for example by stopping the
+   primary first and comparing
+   <function>pg_last_wal_replay_lsn()</function> with
+   <function>pg_last_wal_receive_lsn()</function> on the standby.  Tools
+   that copy relation file blocks directly between nodes, such as
+   <xref linkend="app-pgrewind"/>, likewise require both nodes to be in
+   the same data checksum state.
+  </para>
+  <para>
+   The replay requirement exists because an offline change is recorded
+   only in the control file and has no defined ordering against WAL the
+   node has not replayed yet; see
+   <xref linkend="checksums-offline-enable-disable"/>.  A node stopped
+   before replaying an online checksum state change applies that change
+   when it is restarted, overriding the offline change, and the states of
+   the nodes silently diverge until a later checkpoint record triggers
+   the warning described below.  Because of this it is best not to mix
+   the two mechanisms: change the state of a replication setup either
+   with the offline procedure above or with an online transition, and
+   make sure the previous change has reached every node before starting
+   the next one.
   </para>
   <para>
    If the change is applied inconsistently, each node keeps its own state,
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index db18a8c516e..d88a832c2a8 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -317,6 +317,19 @@
     verify checksums, on an offline cluster.
    </para>
 
+   <para>
+    An offline change provides durability differently from an
+    <link linkend="checksums-online-enable-disable">online change</link>.
+    An online transition is WAL-logged: it is ordered against all other
+    WAL records, it is replayed after a crash, and it propagates to
+    standbys.  An offline change is recorded only in the cluster's
+    control file: it writes no WAL, it is invisible to replication, and
+    it has no defined ordering against WAL the node has not replayed
+    yet.  When a node later replays WAL that contains an online checksum
+    state change, that change takes effect on the node even if it was
+    written before the offline change was made.
+   </para>
+
    <para>
     An offline change only affects the data directory it is run on; the
     new state does not propagate over replication.  In a replication setup
-- 
2.55.0

