Skip to content

Commit f82ec32

Browse files
robertmhaasrobertmhaas
committed
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
1 parent ec7db2b commit f82ec32

37 files changed

+279
-226
lines changed

‎doc/src/sgml/backup.sgml

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -472,7 +472,7 @@ tar -cf backup.tar /usr/local/pgsql/data
472472

473473
<para>
474474
At all times, <productname>PostgreSQL</> maintains a
475-
<firstterm>write ahead log</> (WAL) in the <filename>pg_xlog/</>
475+
<firstterm>write ahead log</> (WAL) in the <filename>pg_wal/</>
476476
subdirectory of the cluster's data directory. The log records
477477
every change made to the database's data files. This log exists
478478
primarily for crash-safety purposes: if the system crashes, the
@@ -616,7 +616,7 @@ archive_command = 'copy "%p" "C:\\server\\archivedir\\%f"' # Windows
616616
<literal>%p</> and <literal>%f</> parameters have been replaced,
617617
the actual command executed might look like this:
618618
<programlisting>
619-
test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065
619+
test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_wal/00000001000000A900000065 /mnt/server/archivedir/00000001000000A900000065
620620
</programlisting>
621621
A similar command will be generated for each new file to be archived.
622622
</para>
@@ -668,9 +668,9 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/
668668
fills, nothing further can be archived until the tape is swapped.
669669
You should ensure that any error condition or request to a human operator
670670
is reported appropriately so that the situation can be
671-
resolved reasonably quickly. The <filename>pg_xlog/</> directory will
671+
resolved reasonably quickly. The <filename>pg_wal/</> directory will
672672
continue to fill with WAL segment files until the situation is resolved.
673-
(If the file system containing <filename>pg_xlog/</> fills up,
673+
(If the file system containing <filename>pg_wal/</> fills up,
674674
<productname>PostgreSQL</> will do a PANIC shutdown. No committed
675675
transactions will be lost, but the database will remain offline until
676676
you free some space.)
@@ -682,7 +682,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/
682682
operation continues even if the archiving process falls a little behind.
683683
If archiving falls significantly behind, this will increase the amount of
684684
data that would be lost in the event of a disaster. It will also mean that
685-
the <filename>pg_xlog/</> directory will contain large numbers of
685+
the <filename>pg_wal/</> directory will contain large numbers of
686686
not-yet-archived segment files, which could eventually exceed available
687687
disk space. You are advised to monitor the archiving process to ensure that
688688
it is working as you intend.
@@ -743,7 +743,7 @@ test ! -f /mnt/server/archivedir/00000001000000A900000065 &amp;&amp; cp pg_xlog/
743743
configuration file reload. If you wish to temporarily stop archiving,
744744
one way to do it is to set <varname>archive_command</> to the empty
745745
string (<literal>''</>).
746-
This will cause WAL files to accumulate in <filename>pg_xlog/</> until a
746+
This will cause WAL files to accumulate in <filename>pg_wal/</> until a
747747
working <varname>archive_command</> is re-established.
748748
</para>
749749
</sect2>
@@ -1062,10 +1062,10 @@ SELECT pg_stop_backup();
10621062

10631063
<para>
10641064
You should, however, omit from the backup the files within the
1065-
cluster's <filename>pg_xlog/</> subdirectory. This
1065+
cluster's <filename>pg_wal/</> subdirectory. This
10661066
slight adjustment is worthwhile because it reduces the risk
10671067
of mistakes when restoring. This is easy to arrange if
1068-
<filename>pg_xlog/</> is a symbolic link pointing to someplace outside
1068+
<filename>pg_wal/</> is a symbolic link pointing to someplace outside
10691069
the cluster directory, which is a common setup anyway for performance
10701070
reasons. You might also want to exclude <filename>postmaster.pid</>
10711071
and <filename>postmaster.opts</>, which record information
@@ -1149,7 +1149,7 @@ SELECT pg_stop_backup();
11491149
location in case you need them later. Note that this precaution will
11501150
require that you have enough free space on your system to hold two
11511151
copies of your existing database. If you do not have enough space,
1152-
you should at least save the contents of the cluster's <filename>pg_xlog</>
1152+
you should at least save the contents of the cluster's <filename>pg_wal</>
11531153
subdirectory, as it might contain logs which
11541154
were not archived before the system went down.
11551155
</para>
@@ -1172,9 +1172,9 @@ SELECT pg_stop_backup();
11721172
</listitem>
11731173
<listitem>
11741174
<para>
1175-
Remove any files present in <filename>pg_xlog/</>; these came from the
1175+
Remove any files present in <filename>pg_wal/</>; these came from the
11761176
file system backup and are therefore probably obsolete rather than current.
1177-
If you didn't archive <filename>pg_xlog/</> at all, then recreate
1177+
If you didn't archive <filename>pg_wal/</> at all, then recreate
11781178
it with proper permissions,
11791179
being careful to ensure that you re-establish it as a symbolic link
11801180
if you had it set up that way before.
@@ -1183,7 +1183,7 @@ SELECT pg_stop_backup();
11831183
<listitem>
11841184
<para>
11851185
If you have unarchived WAL segment files that you saved in step 2,
1186-
copy them into <filename>pg_xlog/</>. (It is best to copy them,
1186+
copy them into <filename>pg_wal/</>. (It is best to copy them,
11871187
not move them, so you still have the unmodified files if a
11881188
problem occurs and you have to start over.)
11891189
</para>
@@ -1265,9 +1265,9 @@ restore_command = 'cp /mnt/server/archivedir/%f %p'
12651265

12661266
<para>
12671267
WAL segments that cannot be found in the archive will be sought in
1268-
<filename>pg_xlog/</>; this allows use of recent un-archived segments.
1268+
<filename>pg_wal/</>; this allows use of recent un-archived segments.
12691269
However, segments that are available from the archive will be used in
1270-
preference to files in <filename>pg_xlog/</>.
1270+
preference to files in <filename>pg_wal/</>.
12711271
</para>
12721272

12731273
<para>

‎doc/src/sgml/config.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2932,7 +2932,7 @@ include_dir 'conf.d'
29322932
<listitem>
29332933
<para>
29342934
Specifies the minimum number of past log file segments kept in the
2935-
<filename>pg_xlog</>
2935+
<filename>pg_wal</>
29362936
directory, in case a standby server needs to fetch them for streaming
29372937
replication. Each segment is normally 16 megabytes. If a standby
29382938
server connected to the sending server falls behind by more than
@@ -2946,7 +2946,7 @@ include_dir 'conf.d'
29462946

29472947
<para>
29482948
This sets only the minimum number of segments retained in
2949-
<filename>pg_xlog</>; the system might need to retain more segments
2949+
<filename>pg_wal</>; the system might need to retain more segments
29502950
for WAL archival or to recover from a checkpoint. If
29512951
<varname>wal_keep_segments</> is zero (the default), the system
29522952
doesn't keep any extra segments for standby purposes, so the number
@@ -3322,7 +3322,7 @@ include_dir 'conf.d'
33223322
<para>
33233323
Specify how long the standby server should wait when WAL data is not
33243324
available from any sources (streaming replication,
3325-
local <filename>pg_xlog</> or WAL archive) before retrying to
3325+
local <filename>pg_wal</> or WAL archive) before retrying to
33263326
retrieve WAL data. This parameter can only be set in the
33273327
<filename>postgresql.conf</> file or on the server command line.
33283328
The default value is 5 seconds. Units are milliseconds if not specified.

‎doc/src/sgml/func.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15327,7 +15327,7 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
1532715327
pg_snapshots | 13
1532815328
pg_multixact | 14
1532915329
PG_VERSION | 15
15330-
pg_xlog | 16
15330+
pg_wal | 16
1533115331
pg_hba.conf | 17
1533215332
pg_stat_tmp | 18
1533315333
pg_subtrans | 19

‎doc/src/sgml/high-availability.sgml

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -594,32 +594,32 @@ protocol to make nodes agree on a serializable transactional order.
594594
(see <xref linkend="restore-command">) or directly from the master
595595
over a TCP connection (streaming replication). The standby server will
596596
also attempt to restore any WAL found in the standby cluster's
597-
<filename>pg_xlog</> directory. That typically happens after a server
597+
<filename>pg_wal</> directory. That typically happens after a server
598598
restart, when the standby replays again WAL that was streamed from the
599599
master before the restart, but you can also manually copy files to
600-
<filename>pg_xlog</> at any time to have them replayed.
600+
<filename>pg_wal</> at any time to have them replayed.
601601
</para>
602602

603603
<para>
604604
At startup, the standby begins by restoring all WAL available in the
605605
archive location, calling <varname>restore_command</>. Once it
606606
reaches the end of WAL available there and <varname>restore_command</>
607-
fails, it tries to restore any WAL available in the <filename>pg_xlog</> directory.
607+
fails, it tries to restore any WAL available in the <filename>pg_wal</> directory.
608608
If that fails, and streaming replication has been configured, the
609609
standby tries to connect to the primary server and start streaming WAL
610-
from the last valid record found in archive or <filename>pg_xlog</>. If that fails
610+
from the last valid record found in archive or <filename>pg_wal</>. If that fails
611611
or streaming replication is not configured, or if the connection is
612612
later disconnected, the standby goes back to step 1 and tries to
613613
restore the file from the archive again. This loop of retries from the
614-
archive, <filename>pg_xlog</>, and via streaming replication goes on until the server
614+
archive, <filename>pg_wal</>, and via streaming replication goes on until the server
615615
is stopped or failover is triggered by a trigger file.
616616
</para>
617617

618618
<para>
619619
Standby mode is exited and the server switches to normal operation
620620
when <command>pg_ctl promote</> is run or a trigger file is found
621621
(<varname>trigger_file</>). Before failover,
622-
any WAL immediately available in the archive or in <filename>pg_xlog</> will be
622+
any WAL immediately available in the archive or in <filename>pg_wal</> will be
623623
restored, but no attempt is made to connect to the master.
624624
</para>
625625
</sect2>
@@ -895,7 +895,7 @@ primary_conninfo = 'host=192.168.1.50 port=5432 user=foo password=foopass'
895895
However, these methods often result in retaining more WAL segments than
896896
required, whereas replication slots retain only the number of segments
897897
known to be needed. An advantage of these methods is that they bound
898-
the space requirement for <literal>pg_xlog</>; there is currently no way
898+
the space requirement for <literal>pg_wal</>; there is currently no way
899899
to do this using replication slots.
900900
</para>
901901
<para>

‎doc/src/sgml/perform.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1612,7 +1612,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
16121612
Increase <xref linkend="guc-max-wal-size"> and <xref
16131613
linkend="guc-checkpoint-timeout"> ; this reduces the frequency
16141614
of checkpoints, but increases the storage requirements of
1615-
<filename>/pg_xlog</>.
1615+
<filename>/pg_wal</>.
16161616
</para>
16171617
</listitem>
16181618

‎doc/src/sgml/protocol.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1947,7 +1947,7 @@ The commands accepted in walsender mode are:
19471947
<para>
19481948
Include the necessary WAL segments in the backup. This will include
19491949
all the files between start and stop backup in the
1950-
<filename>pg_xlog</filename> directory of the base directory tar
1950+
<filename>pg_wal</filename> directory of the base directory tar
19511951
file.
19521952
</para>
19531953
</listitem>
@@ -2076,8 +2076,8 @@ The commands accepted in walsender mode are:
20762076
</listitem>
20772077
<listitem>
20782078
<para>
2079-
<filename>pg_xlog</>, including subdirectories. If the backup is run
2080-
with WAL files included, a synthesized version of <filename>pg_xlog</filename> will be
2079+
<filename>pg_wal</>, including subdirectories. If the backup is run
2080+
with WAL files included, a synthesized version of <filename>pg_wal</filename> will be
20812081
included, but it will only contain the files necessary for the
20822082
backup to work, not the rest of the contents.
20832083
</para>

‎doc/src/sgml/ref/pg_resetxlog.sgml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -173,22 +173,22 @@ PostgreSQL documentation
173173
<para>
174174
The WAL starting address should be
175175
larger than any WAL segment file name currently existing in
176-
the directory <filename>pg_xlog</> under the data directory.
176+
the directory <filename>pg_wal</> under the data directory.
177177
These names are also in hexadecimal and have three parts. The first
178178
part is the <quote>timeline ID</> and should usually be kept the same.
179179
For example, if <filename>00000001000000320000004A</> is the
180-
largest entry in <filename>pg_xlog</>, use <literal>-l 00000001000000320000004B</> or higher.
180+
largest entry in <filename>pg_wal</>, use <literal>-l 00000001000000320000004B</> or higher.
181181
</para>
182182

183183
<note>
184184
<para>
185185
<command>pg_resetxlog</command> itself looks at the files in
186-
<filename>pg_xlog</> and chooses a default <option>-l</> setting
186+
<filename>pg_wal</> and chooses a default <option>-l</> setting
187187
beyond the last existing file name. Therefore, manual adjustment of
188188
<option>-l</> should only be needed if you are aware of WAL segment
189-
files that are not currently present in <filename>pg_xlog</>, such as
189+
files that are not currently present in <filename>pg_wal</>, such as
190190
entries in an offline archive; or if the contents of
191-
<filename>pg_xlog</> have been lost entirely.
191+
<filename>pg_wal</> have been lost entirely.
192192
</para>
193193
</note>
194194
</listitem>

‎doc/src/sgml/ref/pg_rewind.sgml

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

‎doc/src/sgml/ref/pg_xlogdump.sgml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ PostgreSQL documentation
118118
<listitem>
119119
<para>
120120
Directory in which to find log segment files. The default is to search
121-
for them in the <literal>pg_xlog</literal> subdirectory of the current
121+
for them in the <literal>pg_wal</literal> subdirectory of the current
122122
directory.
123123
</para>
124124
</listitem>

‎doc/src/sgml/ref/pgtestfsync.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,8 @@
5757
<para>
5858
Specifies the file name to write test data in.
5959
This file should be in the same file system that the
60-
<filename>pg_xlog</> directory is or will be placed in.
61-
(<filename>pg_xlog</> contains the <acronym>WAL</> files.)
60+
<filename>pg_wal</> directory is or will be placed in.
61+
(<filename>pg_wal</> contains the <acronym>WAL</> files.)
6262
The default is <filename>pg_test_fsync.out</> in the current
6363
directory.
6464
</para>

0 commit comments

Comments
 (0)