From 9e7058af0f7ab70996bf2bd0bd6ea719e2a7ab9c Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Wed, 9 Sep 2026 23:38:11 +0200 Subject: [PATCH v14 5/5] doc: Documentation updates for online checksums Tidy up the state diagram to be more readable and move the para about mismatched states to its own sect2 section. Reported-by: Heikki Linnakangas Discussion: https://postgr.es/m/5b08b4d1-0982-4b77-bac5-3bdffc6583f5@iki.fi --- doc/src/sgml/images/datachecksums.gv | 61 ++++++++-- doc/src/sgml/images/datachecksums.svg | 163 ++++++++++++++++---------- doc/src/sgml/images/meson.build | 1 + doc/src/sgml/wal.sgml | 60 ++++++---- 4 files changed, 189 insertions(+), 96 deletions(-) diff --git a/doc/src/sgml/images/datachecksums.gv b/doc/src/sgml/images/datachecksums.gv index dff3ff7340a..f032555db3e 100644 --- a/doc/src/sgml/images/datachecksums.gv +++ b/doc/src/sgml/images/datachecksums.gv @@ -1,14 +1,49 @@ -digraph G { - A -> B [label="SELECT pg_enable_data_checksums()"]; - B -> C; - D -> A; - C -> D [label="SELECT pg_disable_data_checksums()"]; - E -> A [label=" --no-data-checksums"]; - E -> C [label=" --data-checksums"]; - - A [label="off"]; - B [label="inprogress-on"]; - C [label="on"]; - D [label="inprogress-off"]; - E [label="initdb"]; +digraph "datachecksums_states" { + layout=dot; + node [label="", shape=box, style=filled, fillcolor=gray, width=1.0, fontname="sans-serif"]; + + m1 [label="initdb", shape=Mdiamond]; + + subgraph cluster01 { + label="Online Checksums"; + subgraph agroup1 { + rank=same; + a1; + a3; + } + + subgraph agroup2 { + rank=same; + a2; + a4; + } + + a1 -> a2; + a2 -> a3; + a3 -> a4; + a4 -> a1; + + a1 [fillcolor=lightblue, label="off"]; + a2 [fillcolor=lightgreen, label="inprogress-on"]; + a3 [fillcolor=lightblue, label="on"]; + a4 [fillcolor=lightgreen, label="inprogress-off"]; + } + + subgraph cluster05 { + label="Offline Checksums"; + subgraph bgroup2 { + rank=same; + b1 -> b2; + } + + b2 -> b1; + + b1 [fillcolor=lightblue, label="off"]; + b2 [fillcolor=lightblue, label="on"]; + } + + m1 -> a1; + m1 -> a3; + m1 -> b1; + m1 -> b2; } diff --git a/doc/src/sgml/images/datachecksums.svg b/doc/src/sgml/images/datachecksums.svg index 8c58f42922e..eee57c393c0 100644 --- a/doc/src/sgml/images/datachecksums.svg +++ b/doc/src/sgml/images/datachecksums.svg @@ -1,81 +1,126 @@ - + - - - -G - - + + + +datachecksums_states + + +cluster01 + +Online Checksums + + +cluster05 + +Offline Checksums + + -A - -off +m1 + + + + + +initdb - + -B - -inprogress-on +a1 + +off - - -A->B - - -SELECT pg_enable_data_checksums() + + +m1->a1 + + - + -C - -on +a3 + +on - - -B->C - - + + +m1->a3 + + + + + +b1 + +off + + + +m1->b1 + + + + + +b2 + +on + + + +m1->b2 + + - + -D - -inprogress-off +a2 + +inprogress-on - - -C->D - - -SELECT pg_disable_data_checksums() + + +a1->a2 + + + + + +a4 + +inprogress-off - + -D->A - - +a3->a4 + + - - -E - -initdb + + +a2->a3 + + + + + +a4->a1 + + - + -E->A - - - --no-data-checksums +b1->b2 + + - + -E->C - - - --data-checksums +b2->b1 + + diff --git a/doc/src/sgml/images/meson.build b/doc/src/sgml/images/meson.build index 220e3eaafb8..54e80fb402c 100644 --- a/doc/src/sgml/images/meson.build +++ b/doc/src/sgml/images/meson.build @@ -11,6 +11,7 @@ image_targets = [] fixup_svg_xsl = files('fixup-svg.xsl') all_files = [ + 'datachecksums.gv', 'genetic-algorithm.gv', 'gin.gv', 'pagelayout.txt', diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml index dbbfdae5e4f..edd39ee437f 100644 --- a/doc/src/sgml/wal.sgml +++ b/doc/src/sgml/wal.sgml @@ -316,30 +316,6 @@ application can be used to enable or disable data checksums, as well as 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 - the same change must be applied to all nodes while all of them are - stopped, as described in . A standby - whose state diverges logs a warning but keeps its local setting. The - mismatch persists until the states are brought together again, with - the offline procedure or with an online transition; do this promptly. - - @@ -456,7 +432,43 @@ still required. + + + + Mismatched Data Checksums States in a Replicated Cluster + + The primary and secondaries can end up with different data checksums + states due to the different durability models between offline and online + checksum operations. + + + An online transition is WAL-logged, which means that it is replayed after a + crash, and the transition along with all checksum updates are propagated to + standbys. An offline change is recorded only in the cluster's control + file, it writes no WAL and is invisible to replication. The changes made + to the datafiles to write checksums are not WAL logged. This means that 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. This means that all nodes can + be operated on in parallel, and no additional network traffic or WAL + archive traffic will occur. In a replication setup the same change must be + applied to all nodes while all of them are stopped, as described in + . A standby whose state diverges logs a + warning but keeps its local setting. The mismatch persists until the + states are brought together again, with the offline procedure or with an + online transition. + + + + Running a replicated cluster with different data checksum states on the + different nodes is not supported or recommended. + -- 2.39.3 (Apple Git-146)