Version 2 Attached
There being two places now (plus doing it manually) I decided to write this
material in the WAL chapter as opposed to application-specific Notes. A
new section seemed warranted.
I expanded upon the material regarding using different file systems and
disks.
I would like to add a similar "why" to the mount point recommendation but
don't know what that would be. Suggestions welcomed.
David J.
From 322acd64af51ae837af0d2e608b9e37aeb17baa8 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 | 7 ++--
doc/src/sgml/ref/pg_basebackup.sgml | 15 +++-----
doc/src/sgml/wal.sgml | 55 +++++++++++++++++++++++------
3 files changed, 54 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 0026318485..4193e3e2e1 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -411,8 +411,10 @@ PostgreSQL documentation
<term><option>--waldir=<replaceable class="parameter">directory</replaceable></option></term>
<listitem>
<para>
- This option specifies the directory where the write-ahead log
- should be stored.
+ This option specifies the directory in which to store write-ahead log files.
+ See <xref linkend="wal-internals-relocation"/> for more information.
+ The specified path must be absolute. It will be created, including parents,
+ if missing. Otherwise, the directory must be empty.
</para>
</listitem>
</varlistentry>
@@ -668,6 +670,7 @@ PostgreSQL documentation
<command>initdb</command> can also be invoked via
<command>pg_ctl initdb</command>.
</para>
+
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 9659f76042..2871ae9320 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -324,16 +324,11 @@ PostgreSQL documentation
<term><option>--waldir=<replaceable class="parameter">waldir</replaceable></option></term>
<listitem>
<para>
- Sets the directory to write WAL (write-ahead log) files to.
- By default WAL files will be placed in
- the <filename>pg_wal</filename> subdirectory of the target
- directory, but this option can be used to place them elsewhere.
- <replaceable>waldir</replaceable> must be an absolute path.
- As with the main target directory,
- <replaceable>waldir</replaceable> need not exist already, but if
- it does exist it must be empty.
- This option can only be specified when
- the backup is in plain format.
+ This option specifies the directory in which to store write-ahead log files.
+ See <xref linkend="wal-internals-relocation"/> for more information.
+ The specified path must be absolute. It will be created, including parents,
+ if missing. Otherwise, the directory must be empty.
+ This option can only be specified when the backup is in plain format.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index f3b86b26be..94897be88e 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -877,9 +877,10 @@
</para>
<para>
- <acronym>WAL</acronym> files are stored in the directory
- <filename>pg_wal</filename> under the data directory, as a set of
- segment files, normally each 16 MB in size (but the size can be changed
+ <acronym>WAL</acronym> files are written to the directory
+ <filename>pg_wal</filename> under the data directory
+ (see <xref linkend="wal-internals-relocation"/>).
+ Each file, also called a segment file, is 16 MB in size (but the size can be changed
by altering the <option>--wal-segsize</option> <application>initdb</application> option). Each segment is
divided into pages, normally 8 kB each (this size can be changed via the
<option>--with-wal-blocksize</option> configure option). The WAL record headers
@@ -891,14 +892,6 @@
available stock of numbers.
</para>
- <para>
- It is advantageous if the WAL is located on a different disk from the
- main database files. This can be achieved by moving the
- <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.
- </para>
-
<para>
The aim of <acronym>WAL</acronym> is to ensure that the log is
written before database records are altered, but this can be subverted by
@@ -940,4 +933,44 @@
</para>
</sect1>
+ <sect1 id="wal-internals-relocation" xreflabel="WAL Directory Relocation">
+ <title>Relocating the <acronym>WAL</acronym> Directory</title>
+ <para>
+ The data directory of a <productname>PostgreSQL</productname> cluster always
+ contains an entry named <filename>pg_wal</filename>. This is where
+ <acronym>WAL</acronym> files are written. If this entry is a directory
+ then the files will be physically stored within the same filesystem as the
+ data directory. However, the entry can be a symbolic link, in which case
+ the files will be stored in the filesystem location the link points to.
+ </para>
+ <para>
+ To create a symbolic link during the creation of a cluster, using either
+ <application><xref linkend="app-initdb"/></application> or
+ <application><xref linkend="app-pgbasebackup"/></application>, specify
+ the <option>--waldir</option> option. On an existing, but not running,
+ cluster use operating system commands to move the contents of the
+ <filename>pg_wal</filename> directory to the new location, remove the
+ empty directory, and create the symbolic link named <filename>pg_wal</filename>
+ pointing to the new location.
+ </para>
+ <para>
+ One reason for relocating the <acronym>WAL</acronym> directory is to
+ ensure that even if the data directory runs out of space the writing of
+ <acronym>WAL</acronym> files can continue. For this, the chosen location must
+ be on a different filesystem. Similarly, the optimal filesystem
+ characteristics for the data directory, which involves considerable random
+ read and write <acronym>I/O</acronym>, are different than those for the
+ <acronym>WAL</acronym>, which mainly requires sequential write
+ <acronym>I/O</acronym>. Another reason is to increase the effective
+ <acronym>I/O</acronym> capacity of the cluster by leveraging a separate
+ physical disk for the <acronym>WAL</acronym> files.
+ </para>
+ <para>
+ If the symbolic link does point to another filesystem, or for some other
+ reason involves a mount point on the filesystem the data directory is located
+ on, create a directory under the mount point and use that as the target of
+ the symbolic link.
+ </para>
+ </sect1>
+
</chapter>
--
2.34.1
