Horton

Thread

Commits

  1. doc: Mention online checksum enabling in pg_checksums docs

  1. pg_checksums docs mentioning online functions

    Bruce Momjian <bruce@momjian.us> — 2026-06-04T18:55:33Z

    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  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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

  2. Re: pg_checksums docs mentioning online functions

    Daniel Gustafsson <daniel@yesql.se> — 2026-06-04T19:18:34Z

    > 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

  3. Re: pg_checksums docs mentioning online functions

    Bruce Momjian <bruce@momjian.us> — 2026-06-04T20:12:26Z

    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.

  4. Re: pg_checksums docs mentioning online functions

    Daniel Gustafsson <daniel@yesql.se> — 2026-06-04T20:39:53Z

    > 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

  5. Re: pg_checksums docs mentioning online functions

    Bruce Momjian <bruce@momjian.us> — 2026-06-04T21:08:26Z

    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.

  6. Re: pg_checksums docs mentioning online functions

    Daniel Gustafsson <daniel@yesql.se> — 2026-06-04T22:21:41Z

    > 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