Re: Documentation for initdb option --waldir

On Wed, 2025-03-26 at 17:34 -0700, David G. Johnston wrote:
> + <para>
> + The <filename>pg_wal</filename> subdirectory will always exist within the
> + data directory. This is where <productname>PostgreSQL</productname>
> + sends its write-ahead log (<acronym>WAL</acronym>) files.
> + Specifying the <option>--waldir</option> option turns this subdirectory entry
> + into a symbolic link. In general, this is only useful if the remote location
> + is on a different physical device. An existing directory must be empty and
> + should not be a mount point. The directory will be created
> + (including missing parents) if necessary.
> + </para>

I think that it is very valuable to have WAL on a different file system on the
same storage device. The idea is that growing data files cannot exhaust the
space available for WAL.

How about this:

There is always a <filename>pg_wal</filename> within the data directory.
By default, it is a directory where <productname>PostgreSQL</productname>
places its write-ahead log (<acronym>WAL</acronym>) segment files. If
you create the <acronym>WAL</acronym> location somewhere else using the option
<option>--waldir</option>, <filename>pg_wal</filename> will be created as
a symbolic link pointing to that <acronym>WAL</acronym> location.
If the directory already exists, it must be empty and should not be a mount
point. The directory will be created (including missing parents) if necessary.

Yours,
Laurenz Albe