From 1c65e0f756b07ae033778358e98000c93521f7c5 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Wed, 9 Sep 2026 23:38:11 +0200 Subject: [PATCH v15 5/9] doc: Documentation updates for online checksums A set of documentation updates for the online checksums work, found via manual as well as LLM-guided review. * The state diagram was re-done to be improve readability and be more in line with the look and feel of other diagrams. * Paragraph about mismatched states moved to its own sect2. * The documentation for the functions to enable/ disable checksums failed to mention that they are superuser only. The ACL in the procedure definition was also documenting a less strict model than the code so it was updated to match the docs and code. * The documentation for the checksums progress reporting had accidentally omitted the work "fork" and for th blocks_* columns. The values are per fork but the documentation made it seem they were per relation. Reported-by: Heikki Linnakangas Reported-by: Noah Misch Discussion: https://postgr.es/m/5b08b4d1-0982-4b77-bac5-3bdffc6583f5@iki.fi --- doc/src/sgml/func/func-admin.sgml | 13 +- doc/src/sgml/images/datachecksums.gv | 61 ++++++++-- doc/src/sgml/images/datachecksums.svg | 163 ++++++++++++++++---------- doc/src/sgml/images/meson.build | 1 + doc/src/sgml/monitoring.sgml | 4 +- doc/src/sgml/ref/pg_checksums.sgml | 2 +- doc/src/sgml/wal.sgml | 60 ++++++---- src/include/catalog/pg_proc.dat | 2 +- 8 files changed, 204 insertions(+), 102 deletions(-) diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml index 54eeb42e5bc..8bfd290ce15 100644 --- a/doc/src/sgml/func/func-admin.sgml +++ b/doc/src/sgml/func/func-admin.sgml @@ -3128,7 +3128,8 @@ SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); The functions shown in can - be used to enable or disable data checksums in a running cluster. + be used to enable or disable data checksums in a running cluster. Use of + these functions is restricted to superusers. Changing data checksums can be done in a cluster with concurrent activity @@ -3158,7 +3159,7 @@ SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); pg_enable_data_checksums - pg_enable_data_checksums ( cost_delay int, cost_limit int ) + pg_enable_data_checksums ( cost_delay int , cost_limit int ) void @@ -3174,6 +3175,11 @@ SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); If cost_delay and cost_limit are specified, the process is throttled using the same principles as Cost-based Vacuum Delay. + cost_delay defaults to 0, + cost_limit defaults to 100. + + + This function is restricted to superusers. @@ -3193,6 +3199,9 @@ SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); stopped validating data checksums, the data checksum state will be set to off. + + This function is restricted to superusers. + 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/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 6a4cb9bb144..8614338fcab 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -8339,7 +8339,7 @@ FROM pg_stat_get_backend_idset() AS backendid; blocks_total bigint - The number of blocks in the current relation which will be processed, + The number of blocks in the current relation fork which will be processed, or NULL if the worker process hasn't calculated the number of blocks yet. The launcher process has this set to NULL. @@ -8353,7 +8353,7 @@ FROM pg_stat_get_backend_idset() AS backendid; blocks_done bigint - The number of blocks in the current relation which have been processed. + The number of blocks in the current relation fork which have been processed. The launcher process has this set to NULL. diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml index abc035e5409..5a0bda2eca2 100644 --- a/doc/src/sgml/ref/pg_checksums.sgml +++ b/doc/src/sgml/ref/pg_checksums.sgml @@ -288,7 +288,7 @@ PostgreSQL documentation - The replay requirement in exists + The replay requirement in 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 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. + diff --git a/src/include/catalog/pg_proc.dat b/src/include/catalog/pg_proc.dat index c53ce68c717..674159b3a22 100644 --- a/src/include/catalog/pg_proc.dat +++ b/src/include/catalog/pg_proc.dat @@ -12477,7 +12477,7 @@ prorettype => 'void', proargtypes => 'int4 int4', proallargtypes => '{int4,int4}', proargmodes => '{i,i}', proargnames => '{cost_delay,cost_limit}', proargdefaults => '{0,100}', - prosrc => 'enable_data_checksums', proacl => '{POSTGRES=X}' }, + prosrc => 'enable_data_checksums' }, # collation management functions { oid => '3445', descr => 'import collations from operating system', -- 2.39.3 (Apple Git-146)