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
Attachments:
0001-v1-pg_rewind-doc.patchtext/x-patch; charset=UTF-8; name=0001-v1-pg_rewind-doc.patchDownload
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 5485033ed8c..b305d788a6e 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -97,8 +97,8 @@ PostgreSQL documentation
<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.
</para>
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