Re: Slightly improve initdb --sync-only option's help message

On Thu, Jul 22, 2021 at 10:32:18PM +0000, Bossart, Nathan wrote:
> On 7/6/21, 7:02 PM, "Gurjeet Singh" <gurjeet(at)singh(dot)im> wrote:
> > I think it would be helpful if the help message was slightly more
> > descriptive. Some options:
> >
> > Used in patch:
> > only sync data directory; does not modify any data
> >
> > To match the wording of --sync-only option:
> > write contents of data directory to disk; helpful after --no-sync option
> >
> > Clearly specify the system operation used for the option
> > perform fsync on data directory; helpful after --no-sync option
>
> I think the help message should say exactly what the option does and
> should avoid saying what it does not do or how it may be useful. I
> would suggest the following to match the initdb docs [0]:
>
> -S, --sync-only safely write all database files to disk and exit
>
> IMO the note about the option being helpful after using the --no-sync
> option would fit better in the docs, but I'm struggling to think of a
> use case for using --no-sync and then calling initdb again with
> --sync-only. Why wouldn't you just leave out --no-sync the first
> time?

It's to allow safely running bulk loading with fsync=off - if the bulk load
fails, you can wipe out the partially-loaded cluster and start over.
But then transitioning to a durable state requires not just setting fsync=on,
which enables future fsync calls. It also requires syncing all dirty buffers.

doc/src/sgml/config.sgml- <para>
doc/src/sgml/config.sgml- For reliable recovery when changing <varname>fsync</varname>
doc/src/sgml/config.sgml- off to on, it is necessary to force all modified buffers in the
doc/src/sgml/config.sgml- kernel to durable storage. This can be done while the cluster
doc/src/sgml/config.sgml- is shutdown or while <varname>fsync</varname> is on by running <command>initdb
doc/src/sgml/config.sgml: --sync-only</command>, running <command>sync</command>, unmounting the
doc/src/sgml/config.sgml- file system, or rebooting the server.
doc/src/sgml/config.sgml- </para>

--
Justin