On Wed, Mar 26, 2025 at 2:35 AM PG Doc comments form <nore...@postgresql.org>
wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/17/app-initdb.html
> Description:
>
> Hi all,
>
> During troubleshooting with a customer we found that it might help to know
> that initdb will create a symbolic link from data/pg_wal to the custom
> directory with the option --waldir.
>
>
Thank you for the observation. This indeed seems like something we should
cover in a bit more detail. How does the proposed patch (attached) look?
The main initdb change, added to Notes, is:
The pg_wal subdirectory will always exist within the data directory. This
is where PostgreSQL sends its write-ahead log (WAL) files. Specifying the
--waldir 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.
David J.
From be1ac8d7945668d5e31cb2c8aeabe879bfb9f86e Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <david.g.johns...@gmail.com>
Date: Wed, 26 Mar 2025 17:12:57 -0700
Subject: [PATCH] doc: Explain use of symbolic linking for pg_wal
---
doc/src/sgml/ref/initdb.sgml | 15 ++++++++++++++-
doc/src/sgml/wal.sgml | 2 ++
2 files changed, 16 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 0026318485..fa25e2662d 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -413,6 +413,7 @@ PostgreSQL documentation
<para>
This option specifies the directory where the write-ahead log
should be stored.
+ See <xref linkend="app-initdb-notes"/> for more information.
</para>
</listitem>
</varlistentry>
@@ -661,13 +662,25 @@ PostgreSQL documentation
</refsect1>
- <refsect1>
+ <refsect1 id="app-initdb-notes" xreflabel="Notes">
<title>Notes</title>
<para>
<command>initdb</command> can also be invoked via
<command>pg_ctl initdb</command>.
</para>
+
+ <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>
+
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index f3b86b26be..bd45df0a3b 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -897,6 +897,8 @@
<filename>pg_wal</filename> directory to another location (while the server
is shut down, of course) and creating a symbolic link from the
original location in the main data directory to the new location.
+ <application><xref linkend="app-initdb"/></application> will do this during
+ bootstrap if the <option>--waldir</option> option is specified.
</para>
<para>
--
2.34.1
