From 2182d31568dd652a936f664b2c800f429b0ea7db Mon Sep 17 00:00:00 2001 From: Zsolt Parragi Date: Mon, 31 Aug 2026 08:40:44 +0000 Subject: [PATCH v6 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 pg_checksums on each of them, and - only then restart them. Tools that copy relation file blocks directly - between nodes, such as , 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 + pg_last_wal_replay_lsn() with + pg_last_wal_receive_lsn() on the standby. Tools + that copy relation file blocks directly between nodes, such as + , likewise require both nodes to be in + the same data checksum state. + + + 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 + . 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. 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. + + An offline change provides durability differently from an + online change. + 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. + + 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