Subject: pg_checksums docs mentioning online functions

From: Bruce Momjian <[email-masked]>
Date: Thu, 4 Jun 2026 14:55:33 -0400

Looking at the pg_checksums docs, it says:

	pg_checksums checks, enables or disables data checksums in a
	PostgreSQL cluster. The server must be shut down cleanly before
	running pg_checksums.

Do we want to mention the new functions here that can change the
checksum status without being shut down?

-- 
  Bruce Momjian  <[email-masked]>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Do not let urgent matters crowd out time for investment in the future.

---

From: Daniel Gustafsson <[email-masked]>
Date: Thu, 4 Jun 2026 21:18:34 +0200

> On 4 Jun 2026, at 20:55, Bruce Momjian <[email-masked]> wrote:
> 

Not sure, but perhaps a link back to the main data checksums section (which
documents the online operation among other things) would be in order?
Something like:

--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -57,6 +57,10 @@ PostgreSQL documentation
    rewritten in-place.
    Disabling checksums only updates the file <filename>pg_control</filename>.
   </para>
+
+  <para>
+   For more information on data checksums, see <xref linkend="checksums"/>.
+  </para>
  </refsect1>

--
Daniel Gustafsson

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 4 Jun 2026 16:12:26 -0400

> +   For more information on data checksums, see <xref linkend="checksums"/>.

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.

---

From: Daniel Gustafsson <[email-masked]>
Date: Thu, 4 Jun 2026 22:39:53 +0200

> On 4 Jun 2026, at 22:12, Bruce Momjian <[email-masked]> wrote:

> restriction.  I think we need that explicitly mentioned, and at the top.

How about something like the attached?

--
Daniel Gustafsson

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 4 Jun 2026 17:08:26 -0400

Looks good, just one suggestion:

> +   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.

	... pg_checksums will still process all relation files regardless of
	the progress of online checksum processing. 
	-------------------------------

I think this idea is complex enough that we have to clearly state
"online _checksum_ processing."

---

From: Daniel Gustafsson <[email-masked]>
Date: Fri, 5 Jun 2026 00:21:41 +0200

> On 4 Jun 2026, at 23:08, Bruce Momjian <[email-masked]> wrote:

> Looks good, just one suggestion:

Pushed with your suggestion added to the patch, thanks!

--
Daniel Gustafsson