diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml index 70d762e7332..14f99094fb2 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"]; +digraph "datachecksums_states" { + layout=dot; + node [label="", shape=box, style=filled, fillcolor=gray, width=1.0, fontname="sans-serif"]; - A [label="off"]; - B [label="inprogress-on"]; - C [label="on"]; - D [label="inprogress-off"]; - E [label="initdb"]; + 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 + + - - -D->A - - - - + -E - -initdb +a4 + +inprogress-off - + + +a3->a4 + + + + + +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 49bf6b51c49..62dadf3e86c 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..1adafaf6176 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. - - @@ -428,7 +404,7 @@ I/O: all pages need to have data checksums calculated and written which will generate a lot of dirty pages that will need to be flushed to disk, - as well as WAL logged. + as well as WAL-logged. Replication: When the standby receives the data checksum state change @@ -456,7 +432,43 @@ still required. + + + Mismatched Data Checksum 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 data files 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. +