public inbox for [email protected]
help / color / mirror / Atom feedpg_checksums docs mentioning online functions
6+ messages / 2 participants
[nested] [flat]
* pg_checksums docs mentioning online functions
@ 2026-06-04 18:55 Bruce Momjian <[email protected]>
2026-06-04 19:18 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Bruce Momjian @ 2026-06-04 18:55 UTC (permalink / raw)
To: PostgreSQL-documentation <[email protected]>; +Cc: Daniel Gustafsson <[email protected]>
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 protected]> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_checksums docs mentioning online functions
2026-06-04 18:55 pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
@ 2026-06-04 19:18 ` Daniel Gustafsson <[email protected]>
2026-06-04 20:12 ` Re: pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Daniel Gustafsson @ 2026-06-04 19:18 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: PostgreSQL-documentation <[email protected]>
> On 4 Jun 2026, at 20:55, Bruce Momjian <[email protected]> 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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_checksums docs mentioning online functions
2026-06-04 18:55 pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 19:18 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
@ 2026-06-04 20:12 ` Bruce Momjian <[email protected]>
2026-06-04 20:39 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Bruce Momjian @ 2026-06-04 20:12 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: PostgreSQL-documentation <[email protected]>
On Thu, Jun 4, 2026 at 09:18:34PM +0200, Daniel Gustafsson wrote:
> > On 4 Jun 2026, at 20:55, Bruce Momjian <[email protected]> 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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_checksums docs mentioning online functions
2026-06-04 18:55 pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 19:18 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
2026-06-04 20:12 ` Re: pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
@ 2026-06-04 20:39 ` Daniel Gustafsson <[email protected]>
2026-06-04 21:08 ` Re: pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Daniel Gustafsson @ 2026-06-04 20:39 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: PostgreSQL-documentation <[email protected]>
> On 4 Jun 2026, at 22:12, Bruce Momjian <[email protected]> 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
Attachments:
[application/octet-stream] pg_checksums_docs.diff (2.1K, 2-pg_checksums_docs.diff)
download | inline diff:
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>
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_checksums docs mentioning online functions
2026-06-04 18:55 pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 19:18 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
2026-06-04 20:12 ` Re: pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 20:39 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
@ 2026-06-04 21:08 ` Bruce Momjian <[email protected]>
2026-06-04 22:21 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Bruce Momjian @ 2026-06-04 21:08 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: PostgreSQL-documentation <[email protected]>
On Thu, Jun 4, 2026 at 10:39:53PM +0200, Daniel Gustafsson wrote:
> > On 4 Jun 2026, at 22:12, Bruce Momjian <[email protected]> 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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: pg_checksums docs mentioning online functions
2026-06-04 18:55 pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 19:18 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
2026-06-04 20:12 ` Re: pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 20:39 ` Re: pg_checksums docs mentioning online functions Daniel Gustafsson <[email protected]>
2026-06-04 21:08 ` Re: pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
@ 2026-06-04 22:21 ` Daniel Gustafsson <[email protected]>
0 siblings, 0 replies; 6+ messages in thread
From: Daniel Gustafsson @ 2026-06-04 22:21 UTC (permalink / raw)
To: Bruce Momjian <[email protected]>; +Cc: PostgreSQL-documentation <[email protected]>
> On 4 Jun 2026, at 23:08, Bruce Momjian <[email protected]> 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
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2026-06-04 22:21 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-06-04 18:55 pg_checksums docs mentioning online functions Bruce Momjian <[email protected]>
2026-06-04 19:18 ` Daniel Gustafsson <[email protected]>
2026-06-04 20:12 ` Bruce Momjian <[email protected]>
2026-06-04 20:39 ` Daniel Gustafsson <[email protected]>
2026-06-04 21:08 ` Bruce Momjian <[email protected]>
2026-06-04 22:21 ` Daniel Gustafsson <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox