From: Daniel Gustafsson <daniel@yesql.se>
Message-Id: <39395CB7-5BC5-4A44-9F31-4EAE7DCAC8C1@yesql.se>
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_ABF42708-A945-471B-AC38-082823D0B750"
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3776.700.51.11.12\))
Subject: Re: pg_checksums docs mentioning online functions
Date: Thu, 4 Jun 2026 22:39:53 +0200
In-Reply-To: <aiHcKgvHPx9DyX2I@momjian.us>
Cc: PostgreSQL-documentation <pgsql-docs@lists.postgresql.org>
To: Bruce Momjian <bruce@momjian.us>
References: <aiHKJWa1k28fFTqf@momjian.us>
 <3E59EA84-E150-468A-A316-FC99A009D235@yesql.se> <aiHcKgvHPx9DyX2I@momjian.us>
Archived-At: 
 <https://www.postgresql.org/message-id/39395CB7-5BC5-4A44-9F31-4EAE7DCAC8C1%40yesql.se>
Precedence: bulk


--Apple-Mail=_ABF42708-A945-471B-AC38-082823D0B750
Content-Transfer-Encoding: 7bit
Content-Type: text/plain;
	charset=us-ascii

> On 4 Jun 2026, at 22:12, Bruce Momjian <bruce@momjian.us> wrote:

> My big issue is that we explain the limitation of pg_checksums, but
> don't point readers at the tool that doesn't have that offline
> restriction.  I think we need that explicitly mentioned, and at the top.

How about something like the attached?

--
Daniel Gustafsson


--Apple-Mail=_ABF42708-A945-471B-AC38-082823D0B750
Content-Disposition: attachment;
	filename=pg_checksums_docs.diff
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="pg_checksums_docs.diff"
Content-Transfer-Encoding: 7bit

diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml
index 45890324075..d1048d43f11 100644
--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -38,17 +38,22 @@ PostgreSQL documentation
   <para>
    <application>pg_checksums</application> checks, enables or disables data
    checksums in a <productname>PostgreSQL</productname> cluster.  The server
-   must be shut down cleanly before running
-   <application>pg_checksums</application>. When verifying checksums, the exit
+   must be shut down cleanly before running <application>pg_checksums</application>.
+   Checksums can also be enabled while the cluster is running using
+   <xref linkend="checksums-online-enable-disable"/> processing, see
+   <xref linkend="checksums"/> for further details on the different approaches.
+   When verifying checksums, the exit
    status is zero if there are no checksum errors, and nonzero if at least one
    checksum failure is detected. When enabling or disabling checksums, the
    exit status is nonzero if the operation failed.
   </para>
 
   <para>
-   When enabling checksums, if checksums were in the process of being enabled
-   when the cluster was shut down, <application>pg_checksums</application>
-   will still process all relations regardless of the online processing.
+   When enabling checksums with <application>pg_checksums</application>, if
+   checksums were in the process of being enabled using
+   <xref linkend="checksums-online-enable-disable"/>  when the cluster was shut
+   down, <application>pg_checksums</application> will still process all relation
+   files regardless of progress of the online processing.
   </para>
 
   <para>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index c32931edde3..646076f7e39 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -276,7 +276,7 @@
 
   </sect2>
 
-  <sect2 id="checksums-online-enable-disable">
+  <sect2 id="checksums-online-enable-disable" xreflabel="Online Enabling of Checksums">
    <title>Online Enabling of Checksums</title>
 
    <para>

--Apple-Mail=_ABF42708-A945-471B-AC38-082823D0B750--