On Sun Jan 4, 2026 at 1:02 AM CET, Tom Lane wrote:
Andreas Karlsson <[email protected]> writes:
On 1/4/26 12:26 AM, Jelte Fennema-Nio wrote:
<Moving this discussion to pgsql-docs, with accompanying patch>
If we move the GUC in the documentation shouldn't we also move it in
postgresql.conf.sample? The sections in the documentation and the
sections in the sample config file seem to be the same.
You would also need to change the group that the GUC is assigned to
in guc_parameters.dat. So this isn't really a docs-only patch.
(I agree that the GUC seems misclassified as-is.)
Good points. Attached an updated patch that changes
postgresql.conf.sample and the group too.
I didn't move the thread back to pgsql-hackers though, since changing
the location once more seemed counterproductive. Especially since it's
still a docs change at heart.
From a5a7213ea2394208a2d69c1dcec26017948d2279 Mon Sep 17 00:00:00 2001
From: Jelte Fennema-Nio <[email protected]>
Date: Sun, 4 Jan 2026 00:09:13 +0100
Subject: [PATCH v2] Move recovery_init_sync_method GUC to WAL_RECOVERY group
The recovery_init_sync_method GUC was separated from all other recovery
related GUCS in our docs. This made it pretty hard to find in the docs
if you don't know exactly what you're looking for. This moves it to the
generic "Recovery" section on the WAL page. While it's not really
related to WAL it still seems a much more natural place than the "Error
handling" page. Especially because of the description of this subheading:
> This section describes the settings that apply to recovery in general,
> affecting crash recovery, streaming replication and archive-based
> replication.
To make this doc change it also updates the group and place in
postgresql.conf accordingly. The latter of which also required changing
the section header in postgresql.conf.sample to match the header in the
docs.
The only recovery related GUC that exists that's not on the WAL page is
recovery_min_apply_delay, which is under the Replication->Standby
section. Since that GUC is only valid on standbys that seems like a
sensible choice.
---
doc/src/sgml/config.sgml | 78 +++++++++----------
src/backend/utils/misc/guc_parameters.dat | 2 +-
src/backend/utils/misc/postgresql.conf.sample | 10 +--
3 files changed, 45 insertions(+), 45 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cdfe8e376f0..a38747c937e 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -3991,6 +3991,45 @@ include_dir 'conf.d'
</listitem>
</varlistentry>
+ <varlistentry id="guc-recovery-init-sync-method" xreflabel="recovery_init_sync_method">
+ <term><varname>recovery_init_sync_method</varname> (<type>enum</type>)
+ <indexterm>
+ <primary><varname>recovery_init_sync_method</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ When set to <literal>fsync</literal>, which is the default,
+ <productname>PostgreSQL</productname> will recursively open and
+ synchronize all files in the data directory before crash recovery
+ begins. The search for files will follow symbolic links for the WAL
+ directory and each configured tablespace (but not any other symbolic
+ links). This is intended to make sure that all WAL and data files are
+ durably stored on disk before replaying changes. This applies whenever
+ starting a database cluster that did not shut down cleanly, including
+ copies created with <application>pg_basebackup</application>.
+ </para>
+ <para>
+ On Linux, <literal>syncfs</literal> may be used instead, to ask the
+ operating system to synchronize the file systems that contain the
+ data directory, the WAL files and each tablespace (but not any other
+ file systems that may be reachable through symbolic links). This may
+ be a lot faster than the <literal>fsync</literal> setting, because it
+ doesn't need to open each file one by one. On the other hand, it may
+ be slower if a file system is shared by other applications that
+ modify a lot of files, since those files will also be written to disk.
+ Furthermore, on versions of Linux before 5.8, I/O errors encountered
+ while writing data to disk may not be reported to
+ <productname>PostgreSQL</productname>, and relevant error messages may
+ appear only in kernel logs.
+ </para>
+ <para>
+ This parameter can only be set in the
+ <filename>postgresql.conf</filename> file or on the server command line.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</sect2>
@@ -11714,45 +11753,6 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir'
</listitem>
</varlistentry>
- <varlistentry id="guc-recovery-init-sync-method" xreflabel="recovery_init_sync_method">
- <term><varname>recovery_init_sync_method</varname> (<type>enum</type>)
- <indexterm>
- <primary><varname>recovery_init_sync_method</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- When set to <literal>fsync</literal>, which is the default,
- <productname>PostgreSQL</productname> will recursively open and
- synchronize all files in the data directory before crash recovery
- begins. The search for files will follow symbolic links for the WAL
- directory and each configured tablespace (but not any other symbolic
- links). This is intended to make sure that all WAL and data files are
- durably stored on disk before replaying changes. This applies whenever
- starting a database cluster that did not shut down cleanly, including
- copies created with <application>pg_basebackup</application>.
- </para>
- <para>
- On Linux, <literal>syncfs</literal> may be used instead, to ask the
- operating system to synchronize the file systems that contain the
- data directory, the WAL files and each tablespace (but not any other
- file systems that may be reachable through symbolic links). This may
- be a lot faster than the <literal>fsync</literal> setting, because it
- doesn't need to open each file one by one. On the other hand, it may
- be slower if a file system is shared by other applications that
- modify a lot of files, since those files will also be written to disk.
- Furthermore, on versions of Linux before 5.8, I/O errors encountered
- while writing data to disk may not be reported to
- <productname>PostgreSQL</productname>, and relevant error messages may
- appear only in kernel logs.
- </para>
- <para>
- This parameter can only be set in the
- <filename>postgresql.conf</filename> file or on the server command line.
- </para>
- </listitem>
- </varlistentry>
-
</variablelist>
</sect1>
diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat
index cf87c09ca3b..13295737b49 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -2321,7 +2321,7 @@
boot_val => '""',
},
-{ name => 'recovery_init_sync_method', type => 'enum', context => 'PGC_SIGHUP', group => 'ERROR_HANDLING_OPTIONS',
+{ name => 'recovery_init_sync_method', type => 'enum', context => 'PGC_SIGHUP', group => 'WAL_RECOVERY',
short_desc => 'Sets the method for synchronizing the data directory before crash recovery.',
variable => 'recovery_init_sync_method',
boot_val => 'DATA_DIR_SYNC_METHOD_FSYNC',
diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample
index dc9e2255f8a..6e7472181b3 100644
--- a/src/backend/utils/misc/postgresql.conf.sample
+++ b/src/backend/utils/misc/postgresql.conf.sample
@@ -267,11 +267,12 @@
#max_wal_size = 1GB
#min_wal_size = 80MB
-# - Prefetching during recovery -
+# - Recovery -
-#recovery_prefetch = try # prefetch pages referenced in the WAL?
-#wal_decode_buffer_size = 512kB # lookahead window used for prefetching
- # (change requires restart)
+#recovery_prefetch = try # prefetch pages referenced in the WAL?
+#wal_decode_buffer_size = 512kB # lookahead window used for prefetching
+ # (change requires restart)
+#recovery_init_sync_method = fsync # fsync, syncfs (Linux 5.8+)
# - Archiving -
@@ -868,7 +869,6 @@
#data_sync_retry = off # retry or panic on failure to fsync
# data?
# (change requires restart)
-#recovery_init_sync_method = fsync # fsync, syncfs (Linux 5.8+)
#------------------------------------------------------------------------------
base-commit: 094b61ce3ebbb1258675cb9b4eca9198628e2177
--
2.52.0
