On Sat, 3 Jan 2026 at 20:09, Andreas Karlsson <[email protected]> wrote:
On 1/3/26 1:58 AM, Jelte Fennema-Nio wrote: > PS It took me way to long to find that setting. I think we should move > it from the error handling docs page to the page with all of the other > recovery settings. https://www.postgresql.org/docs/current/runtime- > config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY <https://www.postgresql.org/ > docs/current/runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY> I agree that it is currently not in exactly a great location but the issue is that the "Recovery" section is a subsection of the "WAL" section, and syncing the data directory is only loosely related to WAL. One could argue it is related to WAL as in that it is something done before replaying WAL but it is not an obvious location either. Or is it?
<Moving this discussion to pgsql-docs, with accompanying patch> While the setting is not strictly 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.
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.
From 1ec7e36748ecf3d0c7e4333137c390658dc43e20 Mon Sep 17 00:00:00 2001 From: Jelte Fennema-Nio <[email protected]> Date: Sun, 4 Jan 2026 00:09:13 +0100 Subject: [PATCH v1] docs: Move recovery_init_sync_method to WAL->Recovery section 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. 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 ++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 39 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> base-commit: 094b61ce3ebbb1258675cb9b4eca9198628e2177 -- 2.52.0
