v20250310-0005-update-docs.patch

From 318c3f960707f80a53437635140ab935e936262e Mon Sep 17 00:00:00 2001
From: Tomas Vondra <tomas@vondra.me>
Date: Sun, 9 Mar 2025 13:34:10 +0100
Subject: [PATCH v20250310 5/5] update docs

---
 doc/src/sgml/monitoring.sgml | 84 ++++++++++++++++++++----------------
 doc/src/sgml/wal.sgml        |  8 ++--
 2 files changed, 51 insertions(+), 41 deletions(-)

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 4a6ef5f1605..2a568ee2357 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -6804,8 +6804,8 @@ FROM pg_stat_get_backend_idset() AS backendid;
   <para>
    When data checksums are being enabled on a running cluster, the
    <structname>pg_stat_progress_data_checksums</structname> view will contain
-   a row for each background worker which is currently calculating checksums
-   for the data pages.
+   a row for the launcher process, and one row for each worker process which
+   is currently calculating checksums for the data pages in one database.
   </para>
 
   <table id="pg-stat-progress-data-checksums-view" xreflabel="pg_stat_progress_data_checksums">
@@ -6837,37 +6837,33 @@ FROM pg_stat_get_backend_idset() AS backendid;
      </row>
 
      <row>
-      <entry role="catalog_table_entry">
-       <para role="column_definition">
-        <structfield>phase</structfield> <type>text</type>
-       </para>
-       <para>
-        Current processing phase, see <xref linkend="datachecksum-phases"/>
-        for description of the phases.
-       </para>
-      </entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>datid</structfield> <type>oid</type>
+      </para>
+      <para>
+       OID of this database, or 0 for the launcher process
+       relation
+      </para></entry>
      </row>
 
      <row>
-      <entry role="catalog_table_entry">
-       <para role="column_definition">
-        <structfield>databases_total</structfield> <type>integer</type>
-       </para>
-       <para>
-        The total number of databases which will be processed.
-       </para>
-      </entry>
+      <entry role="catalog_table_entry"><para role="column_definition">
+       <structfield>datname</structfield> <type>name</type>
+      </para>
+      <para>
+       Name of this database, or <literal>NULL</literal> for the
+       launcher process.
+      </para></entry>
      </row>
 
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>relations_total</structfield> <type>integer</type>
+        <structfield>phase</structfield> <type>text</type>
        </para>
        <para>
-        The total number of relations which will be processed, or
-        <literal>NULL</literal> if the data checksums worker process hasn't
-        calculated the number of relations yet.
+        Current processing phase, see <xref linkend="datachecksum-phases"/>
+        for description of the phases.
        </para>
       </entry>
      </row>
@@ -6875,10 +6871,12 @@ FROM pg_stat_get_backend_idset() AS backendid;
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>databases_processed</structfield> <type>integer</type>
+        <structfield>databases_total</structfield> <type>integer</type>
        </para>
        <para>
-        The number of databases which have been processed.
+        The total number of databases which will be processed. Only the
+        launcher worker has this value set, the other worker processes
+        have this <literal>NULL</literal>.
        </para>
       </entry>
      </row>
@@ -6886,10 +6884,12 @@ FROM pg_stat_get_backend_idset() AS backendid;
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>relations_processed</structfield> <type>integer</type>
+        <structfield>databases_done</structfield> <type>integer</type>
        </para>
        <para>
-        The number of relations which have been processed.
+        The number of databases which have been processed. Only the
+        launcher worker has this value set, the other worker processes
+        have this <literal>NULL</literal>.
        </para>
       </entry>
      </row>
@@ -6897,10 +6897,13 @@ FROM pg_stat_get_backend_idset() AS backendid;
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>databases_current</structfield> <type>oid</type>
+        <structfield>relations_total</structfield> <type>integer</type>
        </para>
        <para>
-        OID of the database currently being processed.
+        The total number of relations which will be processed, or
+        <literal>NULL</literal> if the data checksums worker process hasn't
+        calculated the number of relations yet. The launcher process has
+        this <literal>NULL</literal>.
        </para>
       </entry>
      </row>
@@ -6908,10 +6911,11 @@ FROM pg_stat_get_backend_idset() AS backendid;
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>relation_current</structfield> <type>oid</type>
+        <structfield>relations_done</structfield> <type>integer</type>
        </para>
        <para>
-        OID of the relation currently being processed.
+        The number of relations which have been processed. The launcher
+        process has this <literal>NULL</literal>.
        </para>
       </entry>
      </row>
@@ -6919,10 +6923,13 @@ FROM pg_stat_get_backend_idset() AS backendid;
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>relation_current_blocks</structfield> <type>integer</type>
+        <structfield>blocks_total</structfield> <type>integer</type>
        </para>
        <para>
-        The total number of blocks in the relation currently being processed.
+        The number of blocks in the current relation which will be processed,
+        or <literal>NULL</literal> if the data checksums worker process hasn't
+        calculated the number of blocks yet. The launcher process has
+        this <literal>NULL</literal>.
        </para>
       </entry>
      </row>
@@ -6930,11 +6937,11 @@ FROM pg_stat_get_backend_idset() AS backendid;
      <row>
       <entry role="catalog_table_entry">
        <para role="column_definition">
-        <structfield>relation_current_blocks_processed</structfield> <type>integer</type>
+        <structfield>blocks_done</structfield> <type>integer</type>
        </para>
        <para>
-        The number of blocks which have been processed in the relation currently
-        being processed.
+        The number of blocks in the current relation which have been processed.
+        The launcher process has this <literal>NULL</literal>.
        </para>
       </entry>
      </row>
@@ -6982,9 +6989,10 @@ FROM pg_stat_get_backend_idset() AS backendid;
       </entry>
      </row>
      <row>
-      <entry><literal>done</literal></entry>
+      <entry><literal>waiting on checkpoint</literal></entry>
       <entry>
-       The command has finished processing and is exiting.
+       The command is currently waiting for a checkpoint to update the checksum
+       state at the end.
       </entry>
      </row>
     </tbody>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 2562b1a002c..0ada90ca0b1 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -310,15 +310,17 @@
     If the cluster is stopped while in <literal>inprogress-on</literal> mode, for
     any reason, then this process must be restarted manually. To do this,
     re-execute the function <function>pg_enable_data_checksums()</function>
-    once the cluster has been restarted. The background worker will attempt
-    to resume the work from where it was interrupted.
+    once the cluster has been restarted. The process will start over, there is
+    no support for resuming work from where it was interrupted.
    </para>
 
    <note>
     <para>
      Enabling checksums can cause significant I/O to the system, as most of the
      database pages will need to be rewritten, and will be written both to the
-     data files and the WAL.
+     data files and the WAL. The impact may be limited by throttling using the
+     <parameter>cost_delay</parameter> and <parameter>cost_limit</parameter>
+     parameters of the <function>pg_enable_data_checksums</function> function.
     </para>
    </note>
 
-- 
2.48.1