doc: Explain use of symbolic linking for pg_wal

Author: polobo

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>
@@ -695,6 +697,7 @@ PostgreSQL documentation
    <command>initdb</command> can also be invoked via
    <command>pg_ctl initdb</command>.
   </para>
+
  </refsect1>
 
  <refsect1>

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>

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>