Re: Use "WAL segment" instead of "log segment" consistently in user-facing messages

On Fri, Apr 01, 2022 at 10:31:10AM +0900, Kyotaro Horiguchi wrote:
> you should at least save the contents of the cluster's <filename>pg_wal</filename>
> - subdirectory, as it might contain logs which
> + subdirectory, as it might contain WAL files which
> were not archived before the system went down.
>
> The "logs" means acutally "WAL segment (files)" but the concept of
> "segment" is out of focus in the context. So just "file" is used
> there. The same change is applied on dezon of places.

This change seems reasonable to me.

> - disk-space requirements for the <acronym>WAL</acronym> logs are met,
> + disk-space requirements for the <acronym>WAL</acronym> are met,
>
> This might be better be "WAL files" instead of just "WAL".

+1 for "WAL files"

> - <acronym>WAL</acronym> logs are stored in the directory
> + <acronym>WAL</acronym> is stored in the directory
> <filename>pg_wal</filename> under the data directory, as a set of
>
> I'm not sure which is better, use "WAL" as a collective noun, or "WAL
> files" as the cocrete objects.

My vote is for "WAL files" because it was previously "WAL logs."

> - The aim of <acronym>WAL</acronym> is to ensure that the log is
> + The aim of <acronym>WAL</acronym> is to ensure that the WAL record is
> written before database records are altered, but this can be subverted by
>
> This is not a mechanical change. But I think this is correct.

IMO the original wording is fine. I think it is sufficiently clear that
"log" refers to "write-ahead log," and this sentence seems intended to
convey the basic rule of "log before data." However, the rest of the
sentence is a little weird. It's basically saying "the aim of the log is
to ensure that the log is written..." Isn't the aim of the log to record
the database activity? Perhaps we should rewrite it to something like the
following:

A basic rule of WAL is that the log must be written before the database
files are altered, but this can be...

--
Nathan Bossart
Amazon Web Services: https://aws.amazon.com