agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedSecond paragraph a little bit misleading
7+ messages / 3 participants
[nested] [flat]
* Second paragraph a little bit misleading
@ 2025-02-11 14:00 PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: PG Doc comments form @ 2025-02-11 14:00 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: afripowered@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/17/checksums.html
Description:
Hi there,
I think that the first sentence of the second paragraph in this page is a
little bit misleading. The first paragraph states that checksums are not
enabled by default. The first sentence in the second paragraph sounds like
it IS enabled by default when using initdb, but you have to pass -k
explicitly.
As far as I understood, it's a good idea to enable this and that is what the
beginning of the second paragraph means.
Maybe a sentence like "Checksums should normally be enabled when the cluster
is initialized using initdb" instead of "are" - or "It's recommended to
enable Checksums when initializing a cluster using initdb".
regards
Felix
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Second paragraph a little bit misleading
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
@ 2025-02-20 16:38 ` Bruce Momjian <bruce@momjian.us>
2025-02-21 07:25 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2025-02-20 16:38 UTC (permalink / raw)
To: afripowered@gmail.com; pgsql-docs@lists.postgresql.org
On Tue, Feb 11, 2025 at 02:00:10PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/17/checksums.html
> Description:
>
> Hi there,
>
> I think that the first sentence of the second paragraph in this page is a
> little bit misleading. The first paragraph states that checksums are not
> enabled by default. The first sentence in the second paragraph sounds like
> it IS enabled by default when using initdb, but you have to pass -k
> explicitly.
>
> As far as I understood, it's a good idea to enable this and that is what the
> beginning of the second paragraph means.
>
> Maybe a sentence like "Checksums should normally be enabled when the cluster
> is initialized using initdb" instead of "are" - or "It's recommended to
> enable Checksums when initializing a cluster using initdb".
I can see your point. Attached is a doc patch that improves it. I
chose very simple language and plan to backpatch this to all supported
versions.
--
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.
Attachments:
[text/x-diff] checksum.diff (574B, ../../Z7dak8fwxwezBhyh@momjian.us/2-checksum.diff)
download | inline diff:
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 52b5b8f793b..705ca682777 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -246,7 +246,7 @@
</para>
<para>
- Checksums are normally enabled when the cluster is initialized using <link
+ Checksums can be enabled when the cluster is initialized using <link
linkend="app-initdb-data-checksums"><application>initdb</application></link>.
They can also be enabled or disabled at a later time as an offline
operation. Data checksums are enabled or disabled at the full cluster
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Second paragraph a little bit misleading
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
@ 2025-02-21 07:25 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 12:00 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Laurenz Albe @ 2025-02-21 07:25 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; afripowered@gmail.com; pgsql-docs@lists.postgresql.org
On Thu, 2025-02-20 at 11:38 -0500, Bruce Momjian wrote:
> On Tue, Feb 11, 2025 at 02:00:10PM +0000, PG Doc comments form wrote:
> > Page: https://www.postgresql.org/docs/17/checksums.html
> >
> > I think that the first sentence of the second paragraph in this page is a
> > little bit misleading. The first paragraph states that checksums are not
> > enabled by default. The first sentence in the second paragraph sounds like
> > it IS enabled by default when using initdb, but you have to pass -k
> > explicitly.
>
> I can see your point. Attached is a doc patch that improves it. I
> chose very simple language and plan to backpatch this to all supported
> versions.
>
> diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
> index 52b5b8f793b..705ca682777 100644
> --- a/doc/src/sgml/wal.sgml
> +++ b/doc/src/sgml/wal.sgml
> @@ -246,7 +246,7 @@
> </para>
>
> <para>
> - Checksums are normally enabled when the cluster is initialized using <link
> + Checksums can be enabled when the cluster is initialized using <link
> linkend="app-initdb-data-checksums"><application>initdb</application></link>.
> They can also be enabled or disabled at a later time as an offline
> operation. Data checksums are enabled or disabled at the full cluster
The change looks good for the back branches, but the default has changed
in v18: now checksums are the default. So "can be enabled" doesn't sound
right for v18. I'd leave "are normally enabled" in HEAD.
Yours,
Laurenz Albe
--
*E-Mail Disclaimer*
Der Inhalt dieser E-Mail ist ausschliesslich fuer den
bezeichneten Adressaten bestimmt. Wenn Sie nicht der vorgesehene Adressat
dieser E-Mail oder dessen Vertreter sein sollten, so beachten Sie bitte,
dass jede Form der Kenntnisnahme, Veroeffentlichung, Vervielfaeltigung oder
Weitergabe des Inhalts dieser E-Mail unzulaessig ist. Wir bitten Sie, sich
in diesem Fall mit dem Absender der E-Mail in Verbindung zu setzen.
*CONFIDENTIALITY NOTICE & DISCLAIMER
*This message and any attachment are
confidential and may be privileged or otherwise protected from disclosure
and solely for the use of the person(s) or entity to whom it is intended.
If you have received this message in error and are not the intended
recipient, please notify the sender immediately and delete this message and
any attachment from your system. If you are not the intended recipient, be
advised that any use of this message is prohibited and may be unlawful, and
you must not copy this message or attachment or disclose the contents to
any other person.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Second paragraph a little bit misleading
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
2025-02-21 07:25 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
@ 2025-02-21 12:00 ` Bruce Momjian <bruce@momjian.us>
2025-02-21 12:42 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2025-02-21 12:00 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: afripowered@gmail.com; pgsql-docs@lists.postgresql.org
On Fri, Feb 21, 2025 at 08:25:56AM +0100, Laurenz Albe wrote:
> On Thu, 2025-02-20 at 11:38 -0500, Bruce Momjian wrote:
> > On Tue, Feb 11, 2025 at 02:00:10PM +0000, PG Doc comments form wrote:
> > > Page: https://www.postgresql.org/docs/17/checksums.html
> > >
> > > I think that the first sentence of the second paragraph in this page is a
> > > little bit misleading. The first paragraph states that checksums are not
> > > enabled by default. The first sentence in the second paragraph sounds like
> > > it IS enabled by default when using initdb, but you have to pass -k
> > > explicitly.
> >
> > I can see your point. Attached is a doc patch that improves it. I
> > chose very simple language and plan to backpatch this to all supported
> > versions.
> >
> > diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
> > index 52b5b8f793b..705ca682777 100644
> > --- a/doc/src/sgml/wal.sgml
> > +++ b/doc/src/sgml/wal.sgml
> > @@ -246,7 +246,7 @@
> > </para>
> >
> > <para>
> > - Checksums are normally enabled when the cluster is initialized using <link
> > + Checksums can be enabled when the cluster is initialized using <link
> > linkend="app-initdb-data-checksums"><application>initdb</application></link>.
> > They can also be enabled or disabled at a later time as an offline
> > operation. Data checksums are enabled or disabled at the full cluster
>
> The change looks good for the back branches, but the default has changed
> in v18: now checksums are the default. So "can be enabled" doesn't sound
> right for v18. I'd leave "are normally enabled" in HEAD.
Yes, I was confused about that too, but I think we changed the code for
the development branch and if we decide to keep the new default, we will
change the docs later. I didn't want to interfere with that.
--
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.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Second paragraph a little bit misleading
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
2025-02-21 07:25 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 12:00 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
@ 2025-02-21 12:42 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 18:06 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Laurenz Albe @ 2025-02-21 12:42 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: afripowered@gmail.com; pgsql-docs@lists.postgresql.org
On Fri, 2025-02-21 at 07:00 -0500, Bruce Momjian wrote:
> > > diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
> > > index 52b5b8f793b..705ca682777 100644
> > > --- a/doc/src/sgml/wal.sgml
> > > +++ b/doc/src/sgml/wal.sgml
> > > @@ -246,7 +246,7 @@
> > > </para>
> > >
> > > <para>
> > > - Checksums are normally enabled when the cluster is initialized using <link
> > > + Checksums can be enabled when the cluster is initialized using <link
> > > linkend="app-initdb-data-checksums"><application>initdb</application></link>.
> > > They can also be enabled or disabled at a later time as an offline
> > > operation. Data checksums are enabled or disabled at the full cluster
> >
> > The change looks good for the back branches, but the default has changed
> > in v18: now checksums are the default. So "can be enabled" doesn't sound
> > right for v18. I'd leave "are normally enabled" in HEAD.
>
> Yes, I was confused about that too, but I think we changed the code for
> the development branch and if we decide to keep the new default, we will
> change the docs later. I didn't want to interfere with that.
Hmpf. The documentation should always be in sync with the code, right?
So I think it should be left alone in HEAD, and if the checksum change
gets reverted, your patch should be applied to HEAD.
Yours,
Laurenz Albe
--
*E-Mail Disclaimer*
Der Inhalt dieser E-Mail ist ausschliesslich fuer den
bezeichneten Adressaten bestimmt. Wenn Sie nicht der vorgesehene Adressat
dieser E-Mail oder dessen Vertreter sein sollten, so beachten Sie bitte,
dass jede Form der Kenntnisnahme, Veroeffentlichung, Vervielfaeltigung oder
Weitergabe des Inhalts dieser E-Mail unzulaessig ist. Wir bitten Sie, sich
in diesem Fall mit dem Absender der E-Mail in Verbindung zu setzen.
*CONFIDENTIALITY NOTICE & DISCLAIMER
*This message and any attachment are
confidential and may be privileged or otherwise protected from disclosure
and solely for the use of the person(s) or entity to whom it is intended.
If you have received this message in error and are not the intended
recipient, please notify the sender immediately and delete this message and
any attachment from your system. If you are not the intended recipient, be
advised that any use of this message is prohibited and may be unlawful, and
you must not copy this message or attachment or disclose the contents to
any other person.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Second paragraph a little bit misleading
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
2025-02-21 07:25 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 12:00 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
2025-02-21 12:42 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
@ 2025-02-21 18:06 ` Bruce Momjian <bruce@momjian.us>
2025-02-21 21:42 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2025-02-21 18:06 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: afripowered@gmail.com; pgsql-docs@lists.postgresql.org
On Fri, Feb 21, 2025 at 01:42:09PM +0100, Laurenz Albe wrote:
> On Fri, 2025-02-21 at 07:00 -0500, Bruce Momjian wrote:
> > > > diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
> > > > index 52b5b8f793b..705ca682777 100644
> > > > --- a/doc/src/sgml/wal.sgml
> > > > +++ b/doc/src/sgml/wal.sgml
> > > > @@ -246,7 +246,7 @@
> > > > </para>
> > > >
> > > > <para>
> > > > - Checksums are normally enabled when the cluster is initialized using <link
> > > > + Checksums can be enabled when the cluster is initialized using <link
> > > > linkend="app-initdb-data-checksums"><application>initdb</application></link>.
> > > > They can also be enabled or disabled at a later time as an offline
> > > > operation. Data checksums are enabled or disabled at the full cluster
> > >
> > > The change looks good for the back branches, but the default has changed
> > > in v18: now checksums are the default. So "can be enabled" doesn't sound
> > > right for v18. I'd leave "are normally enabled" in HEAD.
> >
> > Yes, I was confused about that too, but I think we changed the code for
> > the development branch and if we decide to keep the new default, we will
> > change the docs later. I didn't want to interfere with that.
>
> Hmpf. The documentation should always be in sync with the code, right?
> So I think it should be left alone in HEAD, and if the checksum change
> gets reverted, your patch should be applied to HEAD.
I see your point, and I now agree that the "Reliability" section was
just overlooked when the data checksum default was changed. I made a
larger patch which improved the wording of data checksum mentions now
that it is the default in master.
I also fixed the Felix-reported problem in all the back branches through
14 --- PG 13 did not have the problem.
Patches attached.
--
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.
Attachments:
[text/x-diff] checksum-old.diff (574B, ../../Z7jAm5QSgzf0kRzy@momjian.us/2-checksum-old.diff)
download | inline diff:
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 52b5b8f793b..705ca682777 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -246,7 +246,7 @@
</para>
<para>
- Checksums are normally enabled when the cluster is initialized using <link
+ Checksums can be enabled when the cluster is initialized using <link
linkend="app-initdb-data-checksums"><application>initdb</application></link>.
They can also be enabled or disabled at a later time as an offline
operation. Data checksums are enabled or disabled at the full cluster
[text/x-diff] master.diff (3.8K, ../../Z7jAm5QSgzf0kRzy@momjian.us/3-master.diff)
download | inline diff:
diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml
index 3af065615bc..a12aa3abf01 100644
--- a/doc/src/sgml/amcheck.sgml
+++ b/doc/src/sgml/amcheck.sgml
@@ -466,8 +466,8 @@ SET client_min_messages = DEBUG1;
</listitem>
<listitem>
<para>
- File system or storage subsystem faults where checksums happen to
- simply not be enabled.
+ File system or storage subsystem faults when data checksums are
+ disabled.
</para>
<para>
Note that <filename>amcheck</filename> examines a page as represented in some
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 71c4f96d054..e698e74e116 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -3532,8 +3532,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
</para>
<para>
Number of data page checksum failures detected in this
- database (or on a shared object), or NULL if data checksums are not
- enabled.
+ database (or on a shared object), or NULL if data checksums are
+ disabled.
</para></entry>
</row>
@@ -3543,8 +3543,8 @@ description | Waiting for a newly initialized WAL file to reach durable storage
</para>
<para>
Time at which the last data page checksum failure was detected in
- this database (or on a shared object), or NULL if data checksums are not
- enabled.
+ this database (or on a shared object), or NULL if data checksums are
+ disabled.
</para></entry>
</row>
diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index 27e0598f74c..487c5d758ff 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -85,7 +85,7 @@ test=# SELECT * FROM page_header(get_raw_page('pg_class', 0));
<para>
The <structfield>checksum</structfield> field is the checksum stored in
the page, which might be incorrect if the page is somehow corrupted. If
- data checksums are not enabled for this instance, then the value stored
+ data checksums are disabled for this instance, then the value stored
is meaningless.
</para>
</listitem>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 52b5b8f793b..4fc09761115 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -194,10 +194,8 @@
</listitem>
<listitem>
<para>
- Data pages are not currently checksummed by default, though full page images
- recorded in WAL records will be protected; see <link
- linkend="app-initdb-data-checksums"><application>initdb</application></link>
- for details about enabling data checksums.
+ Data pages are checksummed by default, and full page images
+ recorded in WAL records are always checksum protected.
</para>
</listitem>
<listitem>
@@ -238,15 +236,15 @@
</indexterm>
<para>
- By default, data pages are not protected by checksums, but this can
- optionally be enabled for a cluster. When enabled, each data page includes
+ By default, data pages are protected by checksums, but this can
+ optionally be disabled for a cluster. When enabled, each data page includes
a checksum that is updated when the page is written and verified each time
the page is read. Only data pages are protected by checksums; internal data
structures and temporary files are not.
</para>
<para>
- Checksums are normally enabled when the cluster is initialized using <link
+ Checksums can be disabled when the cluster is initialized using <link
linkend="app-initdb-data-checksums"><application>initdb</application></link>.
They can also be enabled or disabled at a later time as an offline
operation. Data checksums are enabled or disabled at the full cluster
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Second paragraph a little bit misleading
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
2025-02-21 07:25 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 12:00 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
2025-02-21 12:42 ` Re: Second paragraph a little bit misleading Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 18:06 ` Re: Second paragraph a little bit misleading Bruce Momjian <bruce@momjian.us>
@ 2025-02-21 21:42 ` Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 0 replies; 7+ messages in thread
From: Laurenz Albe @ 2025-02-21 21:42 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: afripowered@gmail.com; pgsql-docs@lists.postgresql.org
On Fri, 2025-02-21 at 13:06 -0500, Bruce Momjian wrote:
> > Hmpf. The documentation should always be in sync with the code, right?
> > So I think it should be left alone in HEAD, and if the checksum change
> > gets reverted, your patch should be applied to HEAD.
>
> I see your point, and I now agree that the "Reliability" section was
> just overlooked when the data checksum default was changed. I made a
> larger patch which improved the wording of data checksum mentions now
> that it is the default in master.
>
> I also fixed the Felix-reported problem in all the back branches through
> 14 --- PG 13 did not have the problem.
>
> Patches attached.
Thanks! These patches look good to me.
Yours,
Laurenz Albe
--
*E-Mail Disclaimer*
Der Inhalt dieser E-Mail ist ausschliesslich fuer den
bezeichneten Adressaten bestimmt. Wenn Sie nicht der vorgesehene Adressat
dieser E-Mail oder dessen Vertreter sein sollten, so beachten Sie bitte,
dass jede Form der Kenntnisnahme, Veroeffentlichung, Vervielfaeltigung oder
Weitergabe des Inhalts dieser E-Mail unzulaessig ist. Wir bitten Sie, sich
in diesem Fall mit dem Absender der E-Mail in Verbindung zu setzen.
*CONFIDENTIALITY NOTICE & DISCLAIMER
*This message and any attachment are
confidential and may be privileged or otherwise protected from disclosure
and solely for the use of the person(s) or entity to whom it is intended.
If you have received this message in error and are not the intended
recipient, please notify the sender immediately and delete this message and
any attachment from your system. If you are not the intended recipient, be
advised that any use of this message is prohibited and may be unlawful, and
you must not copy this message or attachment or disclose the contents to
any other person.
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2025-02-21 21:42 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-02-11 14:00 Second paragraph a little bit misleading PG Doc comments form <noreply@postgresql.org>
2025-02-20 16:38 ` Bruce Momjian <bruce@momjian.us>
2025-02-21 07:25 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 12:00 ` Bruce Momjian <bruce@momjian.us>
2025-02-21 12:42 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-02-21 18:06 ` Bruce Momjian <bruce@momjian.us>
2025-02-21 21:42 ` Laurenz Albe <laurenz.albe@cybertec.at>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox