Rename "pg_xlog" directory to "pg_wal".

"xlog" is not a particularly clear abbreviation for "write-ahead log",
and it sometimes confuses users into believe that the contents of the
"pg_xlog" directory are not critical data, leading to unpleasant
consequences.  So, rename the directory to "pg_wal".

This patch modifies pg_upgrade and pg_basebackup to understand both
the old and new directory layouts; the former is necessary given the
purpose of the tool, while the latter merely avoids an unnecessary
backward-compatibility break.

We may wish to consider renaming other programs, switches, and
functions which still use the old "xlog" naming to also refer to
"wal".  However, that's still under discussion, so let's do just this
much for now.

Discussion: CAB7nPqTeC-8+zux8_-4ZD46V7YPwooeFxgndfsq5Rg8ibLVm1A@mail.gmail.com

Michael Paquier

doc/src/sgml/backup.sgml

@@ -472,7 +472,7 @@ tar -cf backup.tar /usr/local/pgsql/data
 
   <para>
    At all times, <productname>PostgreSQL</> maintains a
-   <firstterm>write ahead log</> (WAL) in the <filename>pg_xlog/</>
+   <firstterm>write ahead log</> (WAL) in the <filename>pg_wal/</>
    subdirectory of the cluster's data directory. The log records
    every change made to the database's data files.  This log exists
    primarily for crash-safety purposes: if the system crashes, the
@@ -616,7 +616,7 @@ archive_command = 'copy "%p" "C:\\server\\archivedir\\%f"'  # Windows
     <literal>%p</> and <literal>%f</> parameters have been replaced,
     the actual command executed might look like this:
 <programlisting>
-test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065
+test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065
 </programlisting>
     A similar command will be generated for each new file to be archived.
    </para>
@@ -668,9 +668,9 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/
     fills, nothing further can be archived until the tape is swapped.
     You should ensure that any error condition or request to a human operator
     is reported appropriately so that the situation can be
-    resolved reasonably quickly. The <filename>pg_xlog/</> directory will
+    resolved reasonably quickly. The <filename>pg_wal/</> directory will
     continue to fill with WAL segment files until the situation is resolved.
-    (If the file system containing <filename>pg_xlog/</> fills up,
+    (If the file system containing <filename>pg_wal/</> fills up,
     <productname>PostgreSQL</> will do a PANIC shutdown.  No committed
     transactions will be lost, but the database will remain offline until
     you free some space.)
@@ -682,7 +682,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/
     operation continues even if the archiving process falls a little behind.
     If archiving falls significantly behind, this will increase the amount of
     data that would be lost in the event of a disaster. It will also mean that
-    the <filename>pg_xlog/</> directory will contain large numbers of
+    the <filename>pg_wal/</> directory will contain large numbers of
     not-yet-archived segment files, which could eventually exceed available
     disk space. You are advised to monitor the archiving process to ensure that
     it is working as you intend.
@@ -743,7 +743,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/
     configuration file reload.  If you wish to temporarily stop archiving,
     one way to do it is to set <varname>archive_command</> to the empty
     string (<literal>''</>).
-    This will cause WAL files to accumulate in <filename>pg_xlog/</> until a
+    This will cause WAL files to accumulate in <filename>pg_wal/</> until a
     working <varname>archive_command</> is re-established.
    </para>
   </sect2>
@@ -1062,10 +1062,10 @@ SELECT pg_stop_backup();
 
    <para>
     You should, however, omit from the backup the files within the
-    cluster's <filename>pg_xlog/</> subdirectory.  This
+    cluster's <filename>pg_wal/</> subdirectory.  This
     slight adjustment is worthwhile because it reduces the risk
     of mistakes when restoring.  This is easy to arrange if
-    <filename>pg_xlog/</> is a symbolic link pointing to someplace outside
+    <filename>pg_wal/</> is a symbolic link pointing to someplace outside
     the cluster directory, which is a common setup anyway for performance
     reasons.  You might also want to exclude <filename>postmaster.pid</>
     and <filename>postmaster.opts</>, which record information
@@ -1149,7 +1149,7 @@ SELECT pg_stop_backup();
      location in case you need them later. Note that this precaution will
      require that you have enough free space on your system to hold two
      copies of your existing database. If you do not have enough space,
-     you should at least save the contents of the cluster's <filename>pg_xlog</>
+     you should at least save the contents of the cluster's <filename>pg_wal</>
      subdirectory, as it might contain logs which
      were not archived before the system went down.
     </para>
@@ -1172,9 +1172,9 @@ SELECT pg_stop_backup();
    </listitem>
    <listitem>
     <para>
-     Remove any files present in <filename>pg_xlog/</>; these came from the
+     Remove any files present in <filename>pg_wal/</>; these came from the
      file system backup and are therefore probably obsolete rather than current.
-     If you didn't archive <filename>pg_xlog/</> at all, then recreate
+     If you didn't archive <filename>pg_wal/</> at all, then recreate
      it with proper permissions,
      being careful to ensure that you re-establish it as a symbolic link
      if you had it set up that way before.
@@ -1183,7 +1183,7 @@ SELECT pg_stop_backup();
    <listitem>
     <para>
      If you have unarchived WAL segment files that you saved in step 2,
-     copy them into <filename>pg_xlog/</>.  (It is best to copy them,
+     copy them into <filename>pg_wal/</>.  (It is best to copy them,
      not move them, so you still have the unmodified files if a
      problem occurs and you have to start over.)
     </para>
@@ -1265,9 +1265,9 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
 
    <para>
     WAL segments that cannot be found in the archive will be sought in
-    <filename>pg_xlog/</>; this allows use of recent un-archived segments.
+    <filename>pg_wal/</>; this allows use of recent un-archived segments.
     However, segments that are available from the archive will be used in
-    preference to files in <filename>pg_xlog/</>.
+    preference to files in <filename>pg_wal/</>.
    </para>
 
    <para>

doc/src/sgml/config.sgml

@@ -2932,7 +2932,7 @@ include_dir 'conf.d'
        <listitem>
        <para>
         Specifies the minimum number of past log file segments kept in the
-        <filename>pg_xlog</>
+        <filename>pg_wal</>
         directory, in case a standby server needs to fetch them for streaming
         replication. Each segment is normally 16 megabytes. If a standby
         server connected to the sending server falls behind by more than
@@ -2946,7 +2946,7 @@ include_dir 'conf.d'
 
        <para>
         This sets only the minimum number of segments retained in
-        <filename>pg_xlog</>; the system might need to retain more segments
+        <filename>pg_wal</>; the system might need to retain more segments
         for WAL archival or to recover from a checkpoint. If
         <varname>wal_keep_segments</> is zero (the default), the system
         doesn't keep any extra segments for standby purposes, so the number
@@ -3322,7 +3322,7 @@ include_dir 'conf.d'
        <para>
         Specify how long the standby server should wait when WAL data is not
         available from any sources (streaming replication,
-        local <filename>pg_xlog</> or WAL archive) before retrying to
+        local <filename>pg_wal</> or WAL archive) before retrying to
         retrieve WAL data.  This parameter can only be set in the
         <filename>postgresql.conf</> file or on the server command line.
         The default value is 5 seconds. Units are milliseconds if not specified.

doc/src/sgml/func.sgml

@@ -15327,7 +15327,7 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
  pg_snapshots    | 13
  pg_multixact    | 14
  PG_VERSION      | 15
- pg_xlog         | 16
+ pg_wal          | 16
  pg_hba.conf     | 17
  pg_stat_tmp     | 18
  pg_subtrans     | 19

doc/src/sgml/high-availability.sgml

@@ -594,24 +594,24 @@ protocol to make nodes agree on a serializable transactional order.
     (see <xref linkend="restore-command">) or directly from the master
     over a TCP connection (streaming replication). The standby server will
     also attempt to restore any WAL found in the standby cluster's
-    <filename>pg_xlog</> directory. That typically happens after a server
+    <filename>pg_wal</> directory. That typically happens after a server
     restart, when the standby replays again WAL that was streamed from the
     master before the restart, but you can also manually copy files to
-    <filename>pg_xlog</> at any time to have them replayed.
+    <filename>pg_wal</> at any time to have them replayed.
    </para>
 
    <para>
     At startup, the standby begins by restoring all WAL available in the
     archive location, calling <varname>restore_command</>. Once it
     reaches the end of WAL available there and <varname>restore_command</>
-    fails, it tries to restore any WAL available in the <filename>pg_xlog</> directory.
+    fails, it tries to restore any WAL available in the <filename>pg_wal</> directory.
     If that fails, and streaming replication has been configured, the
     standby tries to connect to the primary server and start streaming WAL
-    from the last valid record found in archive or <filename>pg_xlog</>. If that fails
+    from the last valid record found in archive or <filename>pg_wal</>. If that fails
     or streaming replication is not configured, or if the connection is
     later disconnected, the standby goes back to step 1 and tries to
     restore the file from the archive again. This loop of retries from the
-    archive, <filename>pg_xlog</>, and via streaming replication goes on until the server
+    archive, <filename>pg_wal</>, and via streaming replication goes on until the server
     is stopped or failover is triggered by a trigger file.
    </para>
 
@@ -619,7 +619,7 @@ protocol to make nodes agree on a serializable transactional order.
     Standby mode is exited and the server switches to normal operation
     when <command>pg_ctl promote</> is run or a trigger file is found
     (<varname>trigger_file</>). Before failover,
-    any WAL immediately available in the archive or in <filename>pg_xlog</> will be
+    any WAL immediately available in the archive or in <filename>pg_wal</> will be
     restored, but no attempt is made to connect to the master.
    </para>
   </sect2>
@@ -895,7 +895,7 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
     However, these methods often result in retaining more WAL segments than
     required, whereas replication slots retain only the number of segments
     known to be needed.  An advantage of these methods is that they bound
-    the space requirement for <literal>pg_xlog</>; there is currently no way
+    the space requirement for <literal>pg_wal</>; there is currently no way
     to do this using replication slots.
    </para>
    <para>

doc/src/sgml/perform.sgml

@@ -1612,7 +1612,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
        Increase <xref linkend="guc-max-wal-size"> and <xref
        linkend="guc-checkpoint-timeout"> ; this reduces the frequency
        of checkpoints, but increases the storage requirements of
-       <filename>/pg_xlog</>.
+       <filename>/pg_wal</>.
       </para>
      </listitem>
 

doc/src/sgml/protocol.sgml

@@ -1947,7 +1947,7 @@ The commands accepted in walsender mode are:
          <para>
           Include the necessary WAL segments in the backup. This will include
           all the files between start and stop backup in the
-          <filename>pg_xlog</filename> directory of the base directory tar
+          <filename>pg_wal</filename> directory of the base directory tar
           file.
          </para>
         </listitem>
@@ -2076,8 +2076,8 @@ The commands accepted in walsender mode are:
        </listitem>
        <listitem>
         <para>
-         <filename>pg_xlog</>, including subdirectories. If the backup is run
-         with WAL files included, a synthesized version of <filename>pg_xlog</filename> will be
+         <filename>pg_wal</>, including subdirectories. If the backup is run
+         with WAL files included, a synthesized version of <filename>pg_wal</filename> will be
          included, but it will only contain the files necessary for the
          backup to work, not the rest of the contents.
         </para>

doc/src/sgml/ref/pg_resetxlog.sgml

@@ -173,22 +173,22 @@ PostgreSQL documentation
      <para>
       The WAL starting address should be
       larger than any WAL segment file name currently existing in
-      the directory <filename>pg_xlog</> under the data directory.
+      the directory <filename>pg_wal</> under the data directory.
       These names are also in hexadecimal and have three parts.  The first
       part is the <quote>timeline ID</> and should usually be kept the same.
       For example, if <filename>00000001000000320000004A</> is the
-      largest entry in <filename>pg_xlog</>, use <literal>-l 00000001000000320000004B</> or higher.
+      largest entry in <filename>pg_wal</>, use <literal>-l 00000001000000320000004B</> or higher.
      </para>
 
      <note>
       <para>
        <command>pg_resetxlog</command> itself looks at the files in
-       <filename>pg_xlog</> and chooses a default <option>-l</> setting
+       <filename>pg_wal</> and chooses a default <option>-l</> setting
        beyond the last existing file name.  Therefore, manual adjustment of
        <option>-l</> should only be needed if you are aware of WAL segment
-       files that are not currently present in <filename>pg_xlog</>, such as
+       files that are not currently present in <filename>pg_wal</>, such as
        entries in an offline archive; or if the contents of
-       <filename>pg_xlog</> have been lost entirely.
+       <filename>pg_wal</> have been lost entirely.
       </para>
      </note>
     </listitem>

doc/src/sgml/ref/pg_rewind.sgml

@@ -61,14 +61,14 @@ PostgreSQL documentation
   <para>
    <application>pg_rewind</> examines the timeline histories of the source
    and target clusters to determine the point where they diverged, and
-   expects to find WAL in the target cluster's <filename>pg_xlog</> directory
+   expects to find WAL in the target cluster's <filename>pg_wal</> directory
    reaching all the way back to the point of divergence. The point of divergence
    can be found either on the target timeline, the source timeline, or their common
    ancestor. In the typical failover scenario where the target cluster was
    shut down soon after the divergence, this is not a problem, but if the
    target cluster ran for a long time after the divergence, the old WAL
    files might no longer be present. In that case, they can be manually
-   copied from the WAL archive to the <filename>pg_xlog</> directory, or
+   copied from the WAL archive to the <filename>pg_wal</> directory, or
    fetched on startup by configuring <filename>recovery.conf</>.  The use of
    <application>pg_rewind</> is not limited to failover, e.g.  a standby
    server can be promoted, run some write transactions, and then rewinded

doc/src/sgml/ref/pg_xlogdump.sgml

@@ -118,7 +118,7 @@ PostgreSQL documentation
       <listitem>
        <para>
         Directory in which to find log segment files.  The default is to search
-        for them in the <literal>pg_xlog</literal> subdirectory of the current
+        for them in the <literal>pg_wal</literal> subdirectory of the current
         directory.
        </para>
       </listitem>

doc/src/sgml/ref/pgtestfsync.sgml

@@ -57,8 +57,8 @@
        <para>
         Specifies the file name to write test data in.
         This file should be in the same file system that the
-        <filename>pg_xlog</> directory is or will be placed in.
-        (<filename>pg_xlog</> contains the <acronym>WAL</> files.)
+        <filename>pg_wal</> directory is or will be placed in.
+        (<filename>pg_wal</> contains the <acronym>WAL</> files.)
         The default is <filename>pg_test_fsync.out</> in the current
         directory.
        </para>

doc/src/sgml/ref/pgupgrade.sgml

@@ -345,7 +345,7 @@ NET STOP postgresql-9.0
      your old cluster
      once you start the new cluster after the upgrade.  Link mode also
      requires that the old and new cluster data directories be in the
-     same file system.  (Tablespaces and <filename>pg_xlog</> can be on
+     same file system.  (Tablespaces and <filename>pg_wal</> can be on
      different file systems.)  See <literal>pg_upgrade --help</> for a full
      list of options.
     </para>
@@ -508,7 +508,7 @@ rsync --archive --delete --hard-links --size-only old_pgdata new_pgdata remote_d
       <para>
        If you have tablespaces, you will need to run a similar
        <application>rsync</> command for each tablespace directory.  If you
-       have relocated <filename>pg_xlog</> outside the data directories,
+       have relocated <filename>pg_wal</> outside the data directories,
        <application>rsync</> must be run on those directories too.
       </para>
      </step>

doc/src/sgml/storage.sgml

@@ -141,7 +141,7 @@ Item
 </row>
 
 <row>
- <entry><filename>pg_xlog</></entry>
+ <entry><filename>pg_wal</></entry>
  <entry>Subdirectory containing WAL (Write Ahead Log) files</entry>
 </row>
 

doc/src/sgml/wal.sgml

@@ -557,7 +557,7 @@
   </para>
 
   <para>
-   The number of WAL segment files in <filename>pg_xlog</> directory depends on
+   The number of WAL segment files in <filename>pg_wal</> directory depends on
    <varname>min_wal_size</>, <varname>max_wal_size</> and
    the amount of WAL generated in previous checkpoint cycles. When old log
    segment files are no longer needed, they are removed or recycled (that is,
@@ -582,7 +582,7 @@
    kept at all times. Also, if WAL archiving is used, old segments can not be
    removed or recycled until they are archived. If WAL archiving cannot keep up
    with the pace that WAL is generated, or if <varname>archive_command</varname>
-   fails repeatedly, old WAL files will accumulate in <filename>pg_xlog</>
+   fails repeatedly, old WAL files will accumulate in <filename>pg_wal</>
    until the situation is resolved. A slow or failed standby server that
    uses a replication slot will have the same effect (see
    <xref linkend="streaming-replication-slots">).
@@ -594,7 +594,7 @@
    which are similar to checkpoints in normal operation: the server forces
    all its state to disk, updates the <filename>pg_control</> file to
    indicate that the already-processed WAL data need not be scanned again,
-   and then recycles any old log segment files in the <filename>pg_xlog</>
+   and then recycles any old log segment files in the <filename>pg_wal</>
    directory.
    Restartpoints can't be performed more frequently than checkpoints in the
    master because restartpoints can only be performed at checkpoint records.
@@ -750,7 +750,7 @@
 
   <para>
    <acronym>WAL</acronym> logs are stored in the directory
-   <filename>pg_xlog</filename> under the data directory, as a set of
+   <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
    by altering the <option>--with-wal-segsize</> configure option when
    building the server).  Each segment is divided into pages, normally
@@ -767,7 +767,7 @@
   <para>
    It is advantageous if the log is located on a different disk from the
    main database files.  This can be achieved by moving the
-   <filename>pg_xlog</filename> directory to another location (while the server
+   <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>