From 322acd64af51ae837af0d2e608b9e37aeb17baa8 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" 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 - 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 for more information. + The specified path must be absolute. It will be created, including parents, + if missing. Otherwise, the directory must be empty. @@ -668,6 +670,7 @@ PostgreSQL documentation initdb can also be invoked via pg_ctl initdb. + 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 - Sets the directory to write WAL (write-ahead log) files to. - By default WAL files will be placed in - the pg_wal subdirectory of the target - directory, but this option can be used to place them elsewhere. - waldir must be an absolute path. - As with the main target directory, - waldir 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 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. 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 @@ - WAL files are stored in the directory - pg_wal under the data directory, as a set of - segment files, normally each 16 MB in size (but the size can be changed + WAL files are written to the directory + pg_wal under the data directory + (see ). + Each file, also called a segment file, is 16 MB in size (but the size can be changed by altering the initdb option). Each segment is divided into pages, normally 8 kB each (this size can be changed via the configure option). The WAL record headers @@ -891,14 +892,6 @@ available stock of numbers. - - It is advantageous if the WAL is located on a different disk from the - main database files. This can be achieved by moving the - pg_wal 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. - - The aim of WAL is to ensure that the log is written before database records are altered, but this can be subverted by @@ -940,4 +933,44 @@ + + Relocating the <acronym>WAL</acronym> Directory + + The data directory of a PostgreSQL cluster always + contains an entry named pg_wal. This is where + WAL 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. + + + To create a symbolic link during the creation of a cluster, using either + or + , specify + the option. On an existing, but not running, + cluster use operating system commands to move the contents of the + pg_wal directory to the new location, remove the + empty directory, and create the symbolic link named pg_wal + pointing to the new location. + + + One reason for relocating the WAL directory is to + ensure that even if the data directory runs out of space the writing of + WAL 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 I/O, are different than those for the + WAL, which mainly requires sequential write + I/O. Another reason is to increase the effective + I/O capacity of the cluster by leveraging a separate + physical disk for the WAL files. + + + 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. + + + -- 2.34.1