From: Bruce Momjian <bruce@momjian.us>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: afripowered@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Second paragraph a little bit misleading
Date: Fri, 21 Feb 2025 13:06:19 -0500
Message-ID: <Z7jAm5QSgzf0kRzy@momjian.us> (raw)
In-Reply-To: <ee89f8397eeceee32fc773e0a235d7f222988096.camel@cybertec.at>
References: <173928241056.707.3989867022954178032@wrigleys.postgresql.org>
<Z7dak8fwxwezBhyh@momjian.us>
<43db6e44e5bc8c6f22eb439c8256f1e1bc135cf7.camel@cybertec.at>
<Z7hq4D_QMwR85DOO@momjian.us>
<ee89f8397eeceee32fc773e0a235d7f222988096.camel@cybertec.at>
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.sgmlindex 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.sgmlindex 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.sgmlindex 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.sgmlindex 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.sgmlindex 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: bruce@momjian.us, laurenz.albe@cybertec.at, afripowered@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Second paragraph a little bit misleading
In-Reply-To: <Z7jAm5QSgzf0kRzy@momjian.us>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox