Обсуждение: doc: update the default of data checksums in the doc of pg_rewind

Hi,

I noticed that the pg_rewind documentation still states that data
checksums is disabled by default, but it has been changed to on since PG18.

Here's a small patch to update this.

Best Regards,
Hou zj

On Wed, Dec 24, 2025 at 4:28 PM Zhijie Hou (Fujitsu)
<houzj.fnst@fujitsu.com> wrote:
>
> Hi,
>
> I noticed that the pg_rewind documentation still states that data
> checksums is disabled by default, but it has been changed to on since PG18.
>
> Here's a small patch to update this.

Thanks for the patch!

-   the cluster was initialized with
<application>initdb</application>.  Neither of these
-   are currently on by default.  <xref linkend="guc-full-page-writes"/>
-   must also be set to <literal>on</literal>, but is enabled by default.
+   the cluster was initialized with <application>initdb</application>
(the latter
+   being the default).  <xref linkend="guc-full-page-writes"/> must also be set
+   to <literal>on</literal>, but is enabled by default.

Isn't "(the default)" enough here instead of "(the latter being the default)"?

Regards,

--
Fujii Masao

> On Dec 24, 2025, at 15:27, Zhijie Hou (Fujitsu) <houzj.fnst@fujitsu.com> wrote:
>
> Hi,
>
> I noticed that the pg_rewind documentation still states that data
> checksums is disabled by default, but it has been changed to on since PG18.
>
> Here's a small patch to update this.
>
> Best Regards,
> Hou zj
> <v1-0001-Fix-outdated-doc-in-pg_rewind.patch>


```
-   the cluster was initialized with <application>initdb</application>.  Neither of these
-   are currently on by default.  <xref linkend="guc-full-page-writes"/>
-   must also be set to <literal>on</literal>, but is enabled by default.
+   the cluster was initialized with <application>initdb</application> (the latter
+   being the default).  <xref linkend="guc-full-page-writes"/> must also be set
+   to <literal>on</literal>, but is enabled by default.
```

I think we can explicitly mention PG18 and later, like:
```
the cluster was initialized with <application>initdb</application>
(data checksums are enabled by default in PostgreSQL 18 and later).
```

I searched over the docs, the usage of “<version> and later” is not rare, for example:
```
  <para>
   <application>pg_amcheck</application> is designed to work with
   <productname>PostgreSQL</productname> 14.0 and later.
  </para>
```

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

On Thursday, December 25, 2025 8:22 AM Chao Li <li.evan.chao@gmail.com> wrote:
> 
> > On Dec 24, 2025, at 15:27, Zhijie Hou (Fujitsu) <houzj.fnst@fujitsu.com>
> wrote:
> >
> > Hi,
> >
> > I noticed that the pg_rewind documentation still states that data
> > checksums is disabled by default, but it has been changed to on since PG18.
> >
> > Here's a small patch to update this.
> >
> > Best Regards,
> > Hou zj
> > <v1-0001-Fix-outdated-doc-in-pg_rewind.patch>
> 
> 
> ```
> -   the cluster was initialized with <application>initdb</application>.  Neither
> of these
> -   are currently on by default.  <xref linkend="guc-full-page-writes"/>
> -   must also be set to <literal>on</literal>, but is enabled by default.
> +   the cluster was initialized with <application>initdb</application> (the
> latter
> +   being the default).  <xref linkend="guc-full-page-writes"/> must also be set
> +   to <literal>on</literal>, but is enabled by default.
> ```
> 
> I think we can explicitly mention PG18 and later, like:
> ```
> the cluster was initialized with <application>initdb</application> (data
> checksums are enabled by default in PostgreSQL 18 and later).
> ```
> 
> I searched over the docs, the usage of “<version> and later” is not rare, for
> example:
> ```
>   <para>
>    <application>pg_amcheck</application> is designed to work with
>    <productname>PostgreSQL</productname> 14.0 and later.
>   </para>
> ```

I think including a version number here is necessary, as pg_rewind is not compatible
with older PostgreSQL versions. It should be the release notes of PostgreSQL 18
to reflect changes in default values, rather than the pg_rewind doc mentioning
a behavior change. (We don't mention version number in initdb's doc as well)

Best Regards,
Hou zj

On Thursday, December 25, 2025 8:04 AM Fujii Masao <masao.fujii@gmail.com> wrote:
> On Wed, Dec 24, 2025 at 4:28 PM Zhijie Hou (Fujitsu)
> <houzj.fnst@fujitsu.com> wrote:
> >
> > Hi,
> >
> > I noticed that the pg_rewind documentation still states that data
> > checksums is disabled by default, but it has been changed to on since PG18.
> >
> > Here's a small patch to update this.
> 
> Thanks for the patch!
> 
> -   the cluster was initialized with
> <application>initdb</application>.  Neither of these
> -   are currently on by default.  <xref linkend="guc-full-page-writes"/>
> -   must also be set to <literal>on</literal>, but is enabled by default.
> +   the cluster was initialized with <application>initdb</application>
> (the latter
> +   being the default).  <xref linkend="guc-full-page-writes"/> must also be set
> +   to <literal>on</literal>, but is enabled by default.
> 
> Isn't "(the default)" enough here instead of "(the latter being the default)"?

Agreed. Here is the updated patch.

Best Regards,
Hou zj

On Thursday, December 25, 2025 11:14 AM Zhijie Hou (Fujitsu) <houzj.fnst@fujitsu.com> wrote:
> On Thursday, December 25, 2025 8:22 AM Chao Li <li.evan.chao@gmail.com>
> wrote:
> >
> > > On Dec 24, 2025, at 15:27, Zhijie Hou (Fujitsu)
> > > <houzj.fnst@fujitsu.com>
> > wrote:
> > >
> > > Hi,
> > >
> > > I noticed that the pg_rewind documentation still states that data
> > > checksums is disabled by default, but it has been changed to on since
> PG18.
> > >
> > > Here's a small patch to update this.
> > >
> > > Best Regards,
> > > Hou zj
> > > <v1-0001-Fix-outdated-doc-in-pg_rewind.patch>
> >
> >
> > ```
> > -   the cluster was initialized with <application>initdb</application>.
> Neither
> > of these
> > -   are currently on by default.  <xref linkend="guc-full-page-writes"/>
> > -   must also be set to <literal>on</literal>, but is enabled by default.
> > +   the cluster was initialized with <application>initdb</application>
> > + (the
> > latter
> > +   being the default).  <xref linkend="guc-full-page-writes"/> must also be
> set
> > +   to <literal>on</literal>, but is enabled by default.
> > ```
> >
> > I think we can explicitly mention PG18 and later, like:
> > ```
> > the cluster was initialized with <application>initdb</application>
> > (data checksums are enabled by default in PostgreSQL 18 and later).
> > ```
> >
> > I searched over the docs, the usage of “<version> and later” is not
> > rare, for
> > example:
> > ```
> >   <para>
> >    <application>pg_amcheck</application> is designed to work with
> >    <productname>PostgreSQL</productname> 14.0 and later.
> >   </para>
> > ```
> 
> I think including a version number here is necessary, as pg_rewind is not
> compatible with older PostgreSQL versions. It should be the release notes of
> PostgreSQL 18 to reflect changes in default values, rather than the pg_rewind
> doc mentioning a behavior change. (We don't mention version number in
> initdb's doc as well)

Sorry, a typo above, 'necessary' -> 'unnecessary'.

Best Regards,
Hou zj