Thread: pg_rewind: Doc update for PostgreSQL 18

Hi,

Attached is a documentation update for pg_rewind since data checksums 
are enabled by default starting from PostgreSQL 18.

Feedback welcome !

Best regards,
  Jesper

On Mon, Jun 09, 2025 at 01:38:09PM -0400, Jesper Pedersen wrote:
>     <application>pg_rewind</application> requires that the target server either has
>     the <xref linkend="guc-wal-log-hints"/> option enabled
>     in <filename>postgresql.conf</filename> or data checksums enabled when
> -   the cluster was initialized with <application>initdb</application>.  Neither of these
> -   are currently on by default.  <xref linkend="guc-full-page-writes"/>
> +   the cluster was initialized with <application>initdb</application>.  Data checksums
> +   are enabled by default starting from PostgreSQL 18.  <xref linkend="guc-full-page-writes"/>
>     must also be set to <literal>on</literal>, but is enabled by default.

+1 for fixing this, but I'd like to bikeshed on the wording a bit.  I think
the above proposal loses information since it doesn't mention that
wal_log_hints is off by default.  But it might be tricky to work in all
those details in a readable fashion.  How about we change it to something
like this:

    pg_rewind requires that the target server has full_page_writes enabled
    and at least one of either wal_log_hints or data checksums (see Section
    28.2) enabled. full_page_writes and data checksums are enabled by
    default, but wal_log_hints is not.

I think we ordinarily try to avoid too many version notes in the docs, and
I see that initdb makes no mention of the fact that the default for data
checksums changed in v18, so my first instinct is to leave that out.

-- 
nathan

Hi Nathan,

On 6/9/25 3:15 PM, Nathan Bossart wrote:
>> +   the cluster was initialized with <application>initdb</application>.  Data checksums
>> +   are enabled by default starting from PostgreSQL 18.  <xref linkend="guc-full-page-writes"/>
>>      must also be set to <literal>on</literal>, but is enabled by default.
> 
> +1 for fixing this, but I'd like to bikeshed on the wording a bit.  I think
> the above proposal loses information since it doesn't mention that
> wal_log_hints is off by default.  But it might be tricky to work in all
> those details in a readable fashion.  How about we change it to something
> like this:
> 
>     pg_rewind requires that the target server has full_page_writes enabled
>     and at least one of either wal_log_hints or data checksums (see Section
>     28.2) enabled. full_page_writes and data checksums are enabled by
>     default, but wal_log_hints is not.
>

Yeah, that is good.

> I think we ordinarily try to avoid too many version notes in the docs, and
> I see that initdb makes no mention of the fact that the default for data
> checksums changed in v18, so my first instinct is to leave that out.

Yes, we can leave the "18" part out since the documentation won't be 
back-ported.

As to initdb it should probably mention data checksums due to 
--no-data-checksums.

Feel free to commit your wording.

Thanks !

Best regards,
  Jesper