mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Adjust documentation for syncfs().

Browse Source 
Commit 8c16ad3b43 created a new appendix for syncfs(), which is
excessive for such a small amount of content.  This commit moves
the description of the caveats to be aware of when using syncfs()
back to the documentation for recovery_init_sync_method.  The
documentation for the other utilities with syncfs() support now
directs readers to recovery_init_sync_method for information about
these caveats.

Reported-by: Peter Eisentraut, Robert Haas
Suggested-by: Robert Haas
Reviewed-by: Robert Haas
Discussion: https://postgr.es/m/42804669-7063-1320-ed37-3226d5f1067d%40eisentraut.org
Discussion: https://postgr.es/m/CA%2BTgmobUiqKr%2BZMCLc5Qap-sXBnjfGUU%2BZBmzYEjUuWyjsGr1g%40mail.gmail.com
This commit is contained in:
Nathan Bossart 2024-03-27 10:23:13 -05:00
parent de7e96bd0f
commit 44a4cca991
11 changed files with 24 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/src/sgml/config.sgml
View File

@ -10870,9 +10870,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
On Linux, <literal>syncfs</literal> may be used instead, to ask the On Linux, <literal>syncfs</literal> may be used instead, to ask the
operating system to synchronize the file systems that contain the operating system to synchronize the file systems that contain the
data directory, the WAL files and each tablespace (but not any other data directory, the WAL files and each tablespace (but not any other
file systems that may be reachable through symbolic links). See file systems that may be reachable through symbolic links). This may
<xref linkend="syncfs"/> for more information about using be a lot faster than the <literal>fsync</literal> setting, because it
<function>syncfs()</function>. 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>
<para> <para>
This parameter can only be set in the This parameter can only be set in the

1
doc/src/sgml/filelist.sgml
View File

@ -182,7 +182,6 @@
<!ENTITY acronyms SYSTEM "acronyms.sgml"> <!ENTITY acronyms SYSTEM "acronyms.sgml">
<!ENTITY glossary SYSTEM "glossary.sgml"> <!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY color SYSTEM "color.sgml"> <!ENTITY color SYSTEM "color.sgml">
<!ENTITY syncfs SYSTEM "syncfs.sgml">
<!ENTITY features-supported SYSTEM "features-supported.sgml"> <!ENTITY features-supported SYSTEM "features-supported.sgml">
<!ENTITY features-unsupported SYSTEM "features-unsupported.sgml"> <!ENTITY features-unsupported SYSTEM "features-unsupported.sgml">

1
doc/src/sgml/postgres.sgml
View File

@ -289,7 +289,6 @@ break is not needed in a wider output rendering.
&acronyms; &acronyms;
&glossary; &glossary;
&color; &color;
&syncfs;
&obsolete; &obsolete;
</part> </part>

4
doc/src/sgml/ref/initdb.sgml
View File

@ -394,8 +394,8 @@ PostgreSQL documentation
On Linux, <literal>syncfs</literal> may be used instead to ask the On Linux, <literal>syncfs</literal> may be used instead to ask the
operating system to synchronize the whole file systems that contain the operating system to synchronize the whole file systems that contain the
data directory, the WAL files, and each tablespace. See data directory, the WAL files, and each tablespace. See
<xref linkend="syncfs"/> for more information about using <xref linkend="guc-recovery-init-sync-method"/> for information about
<function>syncfs()</function>. the caveats to be aware of when using <literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used. This option has no effect when <option>--no-sync</option> is used.

4
doc/src/sgml/ref/pg_basebackup.sgml
View File

@ -642,8 +642,8 @@ PostgreSQL documentation
backup directory. When the plain format is used, backup directory. When the plain format is used,
<command>pg_basebackup</command> will also synchronize the file systems <command>pg_basebackup</command> will also synchronize the file systems
that contain the WAL files and each tablespace. See that contain the WAL files and each tablespace. See
<xref linkend="syncfs"/> for more information about using <xref linkend="guc-recovery-init-sync-method"/> for information about
<function>syncfs()</function>. the caveats to be aware of when using <literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used. This option has no effect when <option>--no-sync</option> is used.

4
doc/src/sgml/ref/pg_checksums.sgml
View File

@ -152,8 +152,8 @@ PostgreSQL documentation
On Linux, <literal>syncfs</literal> may be used instead to ask the On Linux, <literal>syncfs</literal> may be used instead to ask the
operating system to synchronize the whole file systems that contain the operating system to synchronize the whole file systems that contain the
data directory, the WAL files, and each tablespace. See data directory, the WAL files, and each tablespace. See
<xref linkend="syncfs"/> for more information about using <xref linkend="guc-recovery-init-sync-method"/> for information about
<function>syncfs()</function>. the caveats to be aware of when using <literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used. This option has no effect when <option>--no-sync</option> is used.

4
doc/src/sgml/ref/pg_combinebackup.sgml
View File

@ -176,8 +176,8 @@ PostgreSQL documentation
backup directory. When the plain format is used, backup directory. When the plain format is used,
<command>pg_combinebackup</command> will also synchronize the file systems <command>pg_combinebackup</command> will also synchronize the file systems
that contain the WAL files and each tablespace. See that contain the WAL files and each tablespace. See
<xref linkend="syncfs"/> for more information about using <xref linkend="guc-recovery-init-sync-method"/> for information about
<function>syncfs()</function>. the caveats to be aware of when using <literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used. This option has no effect when <option>--no-sync</option> is used.

5
doc/src/sgml/ref/pg_dump.sgml
View File

@ -1319,8 +1319,9 @@ PostgreSQL documentation
<para> <para>
On Linux, <literal>syncfs</literal> may be used instead to ask the On Linux, <literal>syncfs</literal> may be used instead to ask the
operating system to synchronize the whole file system that contains the operating system to synchronize the whole file system that contains the
archive directory. See <xref linkend="syncfs"/> for more information archive directory. See <xref linkend="guc-recovery-init-sync-method"/>
about using <function>syncfs()</function>. for information about the caveats to be aware of when using
<literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used or This option has no effect when <option>--no-sync</option> is used or

4
doc/src/sgml/ref/pg_rewind.sgml
View File

@ -297,8 +297,8 @@ PostgreSQL documentation
On Linux, <literal>syncfs</literal> may be used instead to ask the On Linux, <literal>syncfs</literal> may be used instead to ask the
operating system to synchronize the whole file systems that contain the operating system to synchronize the whole file systems that contain the
data directory, the WAL files, and each tablespace. See data directory, the WAL files, and each tablespace. See
<xref linkend="syncfs"/> for more information about using <xref linkend="guc-recovery-init-sync-method"/> for information about
<function>syncfs()</function>. the caveats to be aware of when using <literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used. This option has no effect when <option>--no-sync</option> is used.

4
doc/src/sgml/ref/pgupgrade.sgml
View File

@ -204,8 +204,8 @@ PostgreSQL documentation
On Linux, <literal>syncfs</literal> may be used instead to ask the On Linux, <literal>syncfs</literal> may be used instead to ask the
operating system to synchronize the whole file systems that contain the operating system to synchronize the whole file systems that contain the
upgraded cluster's data directory, its WAL files, and each tablespace. upgraded cluster's data directory, its WAL files, and each tablespace.
See <xref linkend="syncfs"/> for more information about using See <xref linkend="guc-recovery-init-sync-method"/> for information
<function>syncfs()</function>. about the caveats to be aware of when using <literal>syncfs</literal>.
</para> </para>
<para> <para>
This option has no effect when <option>--no-sync</option> is used. This option has no effect when <option>--no-sync</option> is used.

36
doc/src/sgml/syncfs.sgml
View File

@ -1,36 +0,0 @@
<!-- doc/src/sgml/syncfs.sgml -->
<appendix id="syncfs">
<title><function>syncfs()</function> Caveats</title>
<indexterm zone="syncfs">
<primary>syncfs</primary>
</indexterm>
<para>
On Linux <function>syncfs()</function> may be specified for some
configuration parameters (e.g.,
<xref linkend="guc-recovery-init-sync-method"/>), server applications (e.g.,
<application>pg_upgrade</application>), and client applications (e.g.,
<application>pg_basebackup</application>) that involve synchronizing many
files to disk. <function>syncfs()</function> is advantageous in many cases,
but there are some trade-offs to keep in mind.
</para>
<para>
Since <function>syncfs()</function> instructs the operating system to
synchronize a whole file system, it typically requires many fewer system
calls than using <function>fsync()</function> to synchronize each file one by
one. Therefore, using <function>syncfs()</function> may be a lot faster than
using <function>fsync()</function>. However, 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.
</para>
<para>
Furthermore, on versions of Linux before 5.8, I/O errors encountered while
writing data to disk may not be reported to the calling program, and relevant
error messages may appear only in kernel logs.
</para>
</appendix>