public inbox for [email protected]  

help / color / mirror / Atom feed

From: Robert Haas <[email protected]>
To: Nathan Bossart <[email protected]>
Cc: [email protected] <[email protected]>
Subject: Re: pgsql: Allow using syncfs() in frontend utilities.
Date: Fri, 22 Mar 2024 12:52:15 -0400
Message-ID: <CA+TgmobUiqKr+ZMCLc5Qap-sXBnjfGUU+ZBmzYEjUuWyjsGr1g@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>

On Wed, Sep 6, 2023 at 7:28 PM Nathan Bossart <[email protected]> wrote:
> Allow using syncfs() in frontend utilities.
>
> This commit allows specifying a --sync-method in several frontend
> utilities that must synchronize many files to disk (initdb,
> pg_basebackup, pg_checksums, pg_dump, pg_rewind, and pg_upgrade).
> On Linux, users can specify "syncfs" to synchronize the relevant
> file systems instead of calling fsync() for every single file.  In
> many cases, using syncfs() is much faster.
>
> As with recovery_init_sync_method, this new option comes with some
> caveats.  The descriptions of these caveats have been moved to a
> new appendix section in the documentation.

Hi,

I'd like to complain about this commit's addition of a new appendix. I
do understand the temptation to document caveats like this centrally
instead of in multiple places, but as I've been complaining about over
in the "documentation structure" thread, our top-level documentation
index is too big, and I feel strongly that we need to de-clutter it
rather than cluttering it further. This added a new chapter which is
just 5 sentences long. I understand that this was done because the
same issue applies to a bunch of different utilities and we didn't
want to duplicate this text in all of those places, but I feel like
this approach just doesn't scale. If we did this in every place where
we have this much text that we want to avoid duplicating, we'd soon
have hundreds of appendixes.

What I would suggest we do instead is pick one of the places where
this comes up and document it there, perhaps the
recovery_init_sync_method GUC. And then make the documentation for the
other say something like, you know those issues we documented for
recovery_init_sync_method? Well they also apply to this.

-- 
Robert Haas
EDB: http://www.enterprisedb.com

view thread (9+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: pgsql: Allow using syncfs() in frontend utilities.
  In-Reply-To: <CA+TgmobUiqKr+ZMCLc5Qap-sXBnjfGUU+ZBmzYEjUuWyjsGr1g@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox