pg_checksums docs mentioning online functions

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

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?

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

On Thu, Jun 4, 2026 at 09:18:34PM +0200, Daniel Gustafsson wrote:

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

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?

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>

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.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

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

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

On Thu, Jun 4, 2026 at 10:39:53PM +0200, Daniel Gustafsson wrote:

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?

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

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

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

On 4 Jun 2026, at 23:08, Bruce Momjian <bruce@momjian.us> wrote:
On Thu, Jun 4, 2026 at 10:39:53PM +0200, Daniel Gustafsson wrote:

How about something like the attached?

Looks good, just one suggestion:

Pushed with your suggestion added to the patch, thanks!

--
Daniel Gustafsson