mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-12-09 08:10:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Use the terminology "WAL file" not "log file" more consistently.

Browse Source 
Referring to the WAL as just "log" invites confusion with the
postmaster log, so avoid doing that in docs and error messages.
Also shorten "WAL segment file" to just "WAL file" in various
places.

Bharath Rupireddy, reviewed by Nathan Bossart and Kyotaro Horiguchi

Discussion: https://postgr.es/m/CALj2ACUeXa8tDPaiTLexBDMZ7hgvaN+RTb957-cn5qwv9zf-MQ@mail.gmail.com
This commit is contained in:
Tom Lane 2022-09-14 18:40:58 -04:00
parent 63840526b0
commit 31dcfae83c
14 changed files with 67 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/src/sgml/backup.sgml
View File

@ -1111,7 +1111,7 @@ SELECT * FROM pg_backup_stop(wait_for_archive => true);
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_wal</filename>
subdirectory, as it might contain logs which
subdirectory, as it might contain WAL files which
were not archived before the system went down.
</para>
</listitem>
@ -1189,8 +1189,8 @@ SELECT * FROM pg_backup_stop(wait_for_archive => true);
which tells <productname>PostgreSQL</productname> how to retrieve archived
WAL file segments. Like the <varname>archive_command</varname>, this is
a shell command string. It can contain <literal>%f</literal>, which is
replaced by the name of the desired log file, and <literal>%p</literal>,
which is replaced by the path name to copy the log file to.
replaced by the name of the desired WAL file, and <literal>%p</literal>,
which is replaced by the path name to copy the WAL file to.
(The path name is relative to the current working directory,
i.e., the cluster's data directory.)
Write <literal>%%</literal> if you need to embed an actual <literal>%</literal>
@ -1478,9 +1478,9 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
<link linkend="sql-createtablespace"><command>CREATE TABLESPACE</command></link>
commands are WAL-logged with the literal absolute path, and will
therefore be replayed as tablespace creations with the same
absolute path. This might be undesirable if the log is being
absolute path. This might be undesirable if the WAL is being
replayed on a different machine. It can be dangerous even if the
log is being replayed on the same machine, but into a new data
WAL is being replayed on the same machine, but into a new data
directory: the replay will still overwrite the contents of the
original tablespace. To avoid potential gotchas of this sort,
the best practice is to take a new base backup after creating or
@ -1497,11 +1497,11 @@ archive_command = 'local_backup_script.sh "%p" "%f"'
we might need to fix partially-written disk pages. Depending on
your system hardware and software, the risk of partial writes might
be small enough to ignore, in which case you can significantly
reduce the total volume of archived logs by turning off page
reduce the total volume of archived WAL files by turning off page
snapshots using the <xref linkend="guc-full-page-writes"/>
parameter. (Read the notes and warnings in <xref linkend="wal"/>
before you do so.) Turning off page snapshots does not prevent
use of the logs for PITR operations. An area for future
use of the WAL for PITR operations. An area for future
development is to compress archived WAL data by removing
unnecessary page copies even when <varname>full_page_writes</varname> is
on. In the meantime, administrators might wish to reduce the number

4
doc/src/sgml/config.sgml
View File

@ -4237,7 +4237,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
</term>
<listitem>
<para>
Specifies the minimum size of past log file segments kept in the
Specifies the minimum size of past WAL files kept in the
<filename>pg_wal</filename>
directory, in case a standby server needs to fetch them for streaming
replication. If a standby
@ -4831,7 +4831,7 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
needs to control the amount of time to wait for new WAL data to be
available. For example, in archive recovery, it is possible to
make the recovery more responsive in the detection of a new WAL
log file by reducing the value of this parameter. On a system with
file by reducing the value of this parameter. On a system with
low WAL activity, increasing it reduces the amount of requests necessary
to access WAL archives, something useful for example in cloud
environments where the number of times an infrastructure is accessed

2
doc/src/sgml/protocol.sgml
View File

@ -2717,7 +2717,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<listitem>
<para>
If set to true, the backup will wait until the last required WAL
segment has been archived, or emit a warning if log archiving is
segment has been archived, or emit a warning if WAL archiving is
not enabled. If false, the backup will neither wait nor warn,
leaving the client responsible for ensuring the required log is
available. The default is true.

2
doc/src/sgml/ref/pg_basebackup.sgml
View File

@ -316,7 +316,7 @@ PostgreSQL documentation
backup. This will include all write-ahead logs generated during
the backup. Unless the method <literal>none</literal> is specified,
it is possible to start a postmaster in the target
directory without the need to consult the log archive, thus
directory without the need to consult the WAL archive, thus
making the output a completely standalone backup.
</para>
<para>

10
doc/src/sgml/ref/pg_waldump.sgml
View File

@ -53,7 +53,7 @@ PostgreSQL documentation
<term><replaceable class="parameter">startseg</replaceable></term>
<listitem>
<para>
Start reading at the specified log segment file. This implicitly determines
Start reading at the specified WAL segment file. This implicitly determines
the path in which files will be searched for, and the timeline to use.
</para>
</listitem>
@ -63,7 +63,7 @@ PostgreSQL documentation
<term><replaceable class="parameter">endseg</replaceable></term>
<listitem>
<para>
Stop after reading the specified log segment file.
Stop after reading the specified WAL segment file.
</para>
</listitem>
</varlistentry>
@ -141,7 +141,7 @@ PostgreSQL documentation
<term><option>--path=<replaceable>path</replaceable></option></term>
<listitem>
<para>
Specifies a directory to search for log segment files or a
Specifies a directory to search for WAL segment files or a
directory with a <literal>pg_wal</literal> subdirectory that
contains such files. The default is to search in the current
directory, the <literal>pg_wal</literal> subdirectory of the
@ -203,7 +203,7 @@ PostgreSQL documentation
<listitem>
<para>
WAL location at which to start reading. The default is to start reading
the first valid log record found in the earliest file found.
the first valid WAL record found in the earliest file found.
</para>
</listitem>
</varlistentry>
@ -213,7 +213,7 @@ PostgreSQL documentation
<term><option>--timeline=<replaceable>timeline</replaceable></option></term>
<listitem>
<para>
Timeline from which to read log records. The default is to use the
Timeline from which to read WAL records. The default is to use the
value in <replaceable>startseg</replaceable>, if that is specified; otherwise, the
default is 1.
</para>

60
doc/src/sgml/wal.sgml
View File

@ -297,12 +297,12 @@
transaction processing. Briefly, <acronym>WAL</acronym>'s central
concept is that changes to data files (where tables and indexes
reside) must be written only after those changes have been logged,
that is, after log records describing the changes have been flushed
that is, after WAL records describing the changes have been flushed
to permanent storage. If we follow this procedure, we do not need
to flush data pages to disk on every transaction commit, because we
know that in the event of a crash we will be able to recover the
database using the log: any changes that have not been applied to
the data pages can be redone from the log records. (This is
the data pages can be redone from the WAL records. (This is
roll-forward recovery, also known as REDO.)
</para>
@ -323,15 +323,15 @@
<para>
Using <acronym>WAL</acronym> results in a
significantly reduced number of disk writes, because only the log
significantly reduced number of disk writes, because only the WAL
file needs to be flushed to disk to guarantee that a transaction is
committed, rather than every data file changed by the transaction.
The log file is written sequentially,
and so the cost of syncing the log is much less than the cost of
The WAL file is written sequentially,
and so the cost of syncing the WAL is much less than the cost of
flushing the data pages. This is especially true for servers
handling many small transactions touching different parts of the data
store. Furthermore, when the server is processing many small concurrent
transactions, one <function>fsync</function> of the log file may
transactions, one <function>fsync</function> of the WAL file may
suffice to commit many transactions.
</para>
@ -341,10 +341,10 @@
linkend="continuous-archiving"/>. By archiving the WAL data we can support
reverting to any time instant covered by the available WAL data:
we simply install a prior physical backup of the database, and
replay the WAL log just as far as the desired time. What's more,
replay the WAL just as far as the desired time. What's more,
the physical backup doesn't have to be an instantaneous snapshot
of the database state &mdash; if it is made over some period of time,
then replaying the WAL log for that period will fix any internal
then replaying the WAL for that period will fix any internal
inconsistencies.
</para>
</sect1>
@ -497,15 +497,15 @@
that the heap and index data files have been updated with all
information written before that checkpoint. At checkpoint time, all
dirty data pages are flushed to disk and a special checkpoint record is
written to the log file. (The change records were previously flushed
written to the WAL file. (The change records were previously flushed
to the <acronym>WAL</acronym> files.)
In the event of a crash, the crash recovery procedure looks at the latest
checkpoint record to determine the point in the log (known as the redo
checkpoint record to determine the point in the WAL (known as the redo
record) from which it should start the REDO operation. Any changes made to
data files before that point are guaranteed to be already on disk.
Hence, after a checkpoint, log segments preceding the one containing
Hence, after a checkpoint, WAL segments preceding the one containing
the redo record are no longer needed and can be recycled or removed. (When
<acronym>WAL</acronym> archiving is being done, the log segments must be
<acronym>WAL</acronym> archiving is being done, the WAL segments must be
archived before being recycled or removed.)
</para>
@ -544,7 +544,7 @@
another factor to consider. To ensure data page consistency,
the first modification of a data page after each checkpoint results in
logging the entire page content. In that case,
a smaller checkpoint interval increases the volume of output to the WAL log,
a smaller checkpoint interval increases the volume of output to the WAL,
partially negating the goal of using a smaller interval,
and in any case causing more disk I/O.
</para>
@ -614,10 +614,10 @@
<para>
The number of WAL segment files in <filename>pg_wal</filename> directory depends on
<varname>min_wal_size</varname>, <varname>max_wal_size</varname> and
the amount of WAL generated in previous checkpoint cycles. When old log
the amount of WAL generated in previous checkpoint cycles. When old WAL
segment files are no longer needed, they are removed or recycled (that is,
renamed to become future segments in the numbered sequence). If, due to a
short-term peak of log output rate, <varname>max_wal_size</varname> is
short-term peak of WAL output rate, <varname>max_wal_size</varname> is
exceeded, the unneeded segment files will be removed until the system
gets back under this limit. Below that limit, the system recycles enough
WAL files to cover the estimated need until the next checkpoint, and
@ -650,7 +650,7 @@
which are similar to checkpoints in normal operation: the server forces
all its state to disk, updates the <filename>pg_control</filename> 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_wal</filename>
and then recycles any old WAL segment files in the <filename>pg_wal</filename>
directory.
Restartpoints can't be performed more frequently than checkpoints on the
primary because restartpoints can only be performed at checkpoint records.
@ -676,12 +676,12 @@
insertion) at a time when an exclusive lock is held on affected
data pages, so the operation needs to be as fast as possible. What
is worse, writing <acronym>WAL</acronym> buffers might also force the
creation of a new log segment, which takes even more
creation of a new WAL segment, which takes even more
time. Normally, <acronym>WAL</acronym> buffers should be written
and flushed by an <function>XLogFlush</function> request, which is
made, for the most part, at transaction commit time to ensure that
transaction records are flushed to permanent storage. On systems
with high log output, <function>XLogFlush</function> requests might
with high WAL output, <function>XLogFlush</function> requests might
not occur often enough to prevent <function>XLogInsertRecord</function>
from having to do writes. On such systems
one should increase the number of <acronym>WAL</acronym> buffers by
@ -724,7 +724,7 @@
<varname>commit_delay</varname>, so this value is recommended as the
starting point to use when optimizing for a particular workload. While
tuning <varname>commit_delay</varname> is particularly useful when the
WAL log is stored on high-latency rotating disks, benefits can be
WAL is stored on high-latency rotating disks, benefits can be
significant even on storage media with very fast sync times, such as
solid-state drives or RAID arrays with a battery-backed write cache;
but this should definitely be tested against a representative workload.
@ -828,16 +828,16 @@
<para>
<acronym>WAL</acronym> is automatically enabled; no action is
required from the administrator except ensuring that the
disk-space requirements for the <acronym>WAL</acronym> logs are met,
disk-space requirements for the <acronym>WAL</acronym> files are met,
and that any necessary tuning is done (see <xref
linkend="wal-configuration"/>).
</para>
<para>
<acronym>WAL</acronym> records are appended to the <acronym>WAL</acronym>
logs as each new record is written. The insert position is described by
files as each new record is written. The insert position is described by
a Log Sequence Number (<acronym>LSN</acronym>) that is a byte offset into
the logs, increasing monotonically with each new record.
the WAL, increasing monotonically with each new record.
<acronym>LSN</acronym> values are returned as the datatype
<link linkend="datatype-pg-lsn"><type>pg_lsn</type></link>. Values can be
compared to calculate the volume of <acronym>WAL</acronym> data that
@ -846,12 +846,12 @@
</para>
<para>
<acronym>WAL</acronym> logs are stored in the directory
<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
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 log record headers
<option>--with-wal-blocksize</option> configure option). The WAL record headers
are described in <filename>access/xlogrecord.h</filename>; the record
content is dependent on the type of event that is being logged. Segment
files are given ever-increasing numbers as names, starting at
@ -861,7 +861,7 @@
</para>
<para>
It is advantageous if the log is located on a different disk from the
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
@ -877,19 +877,19 @@
on the disk. A power failure in such a situation might lead to
irrecoverable data corruption. Administrators should try to ensure
that disks holding <productname>PostgreSQL</productname>'s
<acronym>WAL</acronym> log files do not make such false reports.
<acronym>WAL</acronym> files do not make such false reports.
(See <xref linkend="wal-reliability"/>.)
</para>
<para>
After a checkpoint has been made and the log flushed, the
After a checkpoint has been made and the WAL flushed, the
checkpoint's position is saved in the file
<filename>pg_control</filename>. Therefore, at the start of recovery,
the server first reads <filename>pg_control</filename> and
then the checkpoint record; then it performs the REDO operation by
scanning forward from the log location indicated in the checkpoint
scanning forward from the WAL location indicated in the checkpoint
record. Because the entire content of data pages is saved in the
log on the first page modification after a checkpoint (assuming
WAL on the first page modification after a checkpoint (assuming
<xref linkend="guc-full-page-writes"/> is not disabled), all pages
changed since the checkpoint will be restored to a consistent
state.
@ -897,7 +897,7 @@
<para>
To deal with the case where <filename>pg_control</filename> is
corrupt, we should support the possibility of scanning existing log
corrupt, we should support the possibility of scanning existing WAL
segments in reverse order &mdash; newest to oldest &mdash; in order to find the
latest checkpoint. This has not been implemented yet.
<filename>pg_control</filename> is small enough (less than one disk page)

10
src/backend/access/transam/xlogreader.c
View File

@ -1229,7 +1229,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
"invalid magic number %04X in log segment %s, offset %u",
"invalid magic number %04X in WAL segment %s, offset %u",
hdr->xlp_magic,
fname,
offset);
@ -1243,7 +1243,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
"invalid info bits %04X in log segment %s, offset %u",
"invalid info bits %04X in WAL segment %s, offset %u",
hdr->xlp_info,
fname,
offset);
@ -1284,7 +1284,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
/* hmm, first page of file doesn't have a long header? */
report_invalid_record(state,
"invalid info bits %04X in log segment %s, offset %u",
"invalid info bits %04X in WAL segment %s, offset %u",
hdr->xlp_info,
fname,
offset);
@ -1303,7 +1303,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
"unexpected pageaddr %X/%X in log segment %s, offset %u",
"unexpected pageaddr %X/%X in WAL segment %s, offset %u",
LSN_FORMAT_ARGS(hdr->xlp_pageaddr),
fname,
offset);
@ -1328,7 +1328,7 @@ XLogReaderValidatePageHeader(XLogReaderState *state, XLogRecPtr recptr,
XLogFileName(fname, state->seg.ws_tli, segno, state->segcxt.ws_segsize);
report_invalid_record(state,
"out-of-sequence timeline ID %u (after %u) in log segment %s, offset %u",
"out-of-sequence timeline ID %u (after %u) in WAL segment %s, offset %u",
hdr->xlp_tli,
state->latestPageTLI,
fname,

6
src/backend/access/transam/xlogrecovery.c
View File

@ -3079,7 +3079,7 @@ ReadRecord(XLogPrefetcher *xlogprefetcher, int emode,
XLogFileName(fname, xlogreader->seg.ws_tli, segno,
wal_segment_size);
ereport(emode_for_corrupt_record(emode, xlogreader->EndRecPtr),
(errmsg("unexpected timeline ID %u in log segment %s, offset %u",
(errmsg("unexpected timeline ID %u in WAL segment %s, offset %u",
xlogreader->latestPageTLI,
fname,
offset)));
@ -3284,13 +3284,13 @@ retry:
errno = save_errno;
ereport(emode_for_corrupt_record(emode, targetPagePtr + reqLen),
(errcode_for_file_access(),
errmsg("could not read from log segment %s, offset %u: %m",
errmsg("could not read from WAL segment %s, offset %u: %m",
fname, readOff)));
}
else
ereport(emode_for_corrupt_record(emode, targetPagePtr + reqLen),
(errcode(ERRCODE_DATA_CORRUPTED),
errmsg("could not read from log segment %s, offset %u: read %d of %zu",
errmsg("could not read from WAL segment %s, offset %u: read %d of %zu",
fname, readOff, r, (Size) XLOG_BLCKSZ)));
goto next_record_is_invalid;
}

4
src/backend/access/transam/xlogutils.c
View File

@ -1051,14 +1051,14 @@ WALReadRaiseError(WALReadError *errinfo)
errno = errinfo->wre_errno;
ereport(ERROR,
(errcode_for_file_access(),
errmsg("could not read from log segment %s, offset %d: %m",
errmsg("could not read from WAL segment %s, offset %d: %m",
fname, errinfo->wre_off)));
}
else if (errinfo->wre_read == 0)
{
ereport(ERROR,
(errcode(ERRCODE_DATA_CORRUPTED),
errmsg("could not read from log segment %s, offset %d: read %d of %d",
errmsg("could not read from WAL segment %s, offset %d: read %d of %d",
fname, errinfo->wre_off, errinfo->wre_read,
errinfo->wre_req)));
}

6
src/backend/replication/walreceiver.c
View File

@ -616,7 +616,7 @@ WalReceiverMain(void)
if (close(recvFile) != 0)
ereport(PANIC,
(errcode_for_file_access(),
errmsg("could not close log segment %s: %m",
errmsg("could not close WAL segment %s: %m",
xlogfname)));
/*
@ -930,7 +930,7 @@ XLogWalRcvWrite(char *buf, Size nbytes, XLogRecPtr recptr, TimeLineID tli)
errno = save_errno;
ereport(PANIC,
(errcode_for_file_access(),
errmsg("could not write to log segment %s "
errmsg("could not write to WAL segment %s "
"at offset %u, length %lu: %m",
xlogfname, startoff, (unsigned long) segbytes)));
}
@ -1042,7 +1042,7 @@ XLogWalRcvClose(XLogRecPtr recptr, TimeLineID tli)
if (close(recvFile) != 0)
ereport(PANIC,
(errcode_for_file_access(),
errmsg("could not close log segment %s: %m",
errmsg("could not close WAL segment %s: %m",
xlogfname)));
/*

8
src/backend/utils/misc/postgresql.conf.sample
View File

@ -251,21 +251,21 @@
#archive_mode = off # enables archiving; off, on, or always
# (change requires restart)
#archive_library = '' # library to use to archive a logfile segment
#archive_library = '' # library to use to archive a WAL file
# (empty string indicates archive_command should
# be used)
#archive_command = '' # command to use to archive a logfile segment
#archive_command = '' # command to use to archive a WAL file
# placeholders: %p = path of file to archive
# %f = file name only
# e.g. 'test ! -f /mnt/server/archivedir/%f && cp %p /mnt/server/archivedir/%f'
#archive_timeout = 0 # force a logfile segment switch after this
#archive_timeout = 0 # force a WAL file switch after this
# number of seconds; 0 disables
# - Archive Recovery -
# These are only used in recovery mode.
#restore_command = '' # command to use to restore an archived logfile segment
#restore_command = '' # command to use to restore an archived WAL file
# placeholders: %p = path of file to restore
# %f = file name only
# e.g. 'cp /mnt/server/archivedir/%f %p'

2
src/bin/pg_resetwal/pg_resetwal.c
View File

@ -788,7 +788,7 @@ PrintNewControlValues(void)
XLogFileName(fname, ControlFile.checkPointCopy.ThisTimeLineID,
newXlogSegNo, WalSegSz);
printf(_("First log segment after reset: %s\n"), fname);
printf(_("First WAL segment after reset: %s\n"), fname);
if (set_mxid != 0)
{

2
src/bin/pg_upgrade/controldata.c
View File

@ -348,7 +348,7 @@ get_control_data(ClusterInfo *cluster, bool live_check)
cluster->controldata.chkpnt_nxtmxoff = str2uint(p);
got_mxoff = true;
}
else if ((p = strstr(bufin, "First log segment after reset:")) != NULL)
else if ((p = strstr(bufin, "First WAL segment after reset:")) != NULL)
{
/* Skip the colon and any whitespace after it */
p = strchr(p, ':');

4
src/bin/pg_waldump/pg_waldump.c
View File

@ -667,7 +667,7 @@ usage(void)
printf(_(" -F, --fork=FORK only show records that modify blocks in fork FORK;\n"
" valid names are main, fsm, vm, init\n"));
printf(_(" -n, --limit=N number of records to display\n"));
printf(_(" -p, --path=PATH directory in which to find log segment files or a\n"
printf(_(" -p, --path=PATH directory in which to find WAL segment files or a\n"
" directory with a ./pg_wal that contains such files\n"
" (default: current directory, ./pg_wal, $PGDATA/pg_wal)\n"));
printf(_(" -q, --quiet do not print any output, except for errors\n"));
@ -675,7 +675,7 @@ usage(void)
" use --rmgr=list to list valid resource manager names\n"));
printf(_(" -R, --relation=T/D/R only show records that modify blocks in relation T/D/R\n"));
printf(_(" -s, --start=RECPTR start reading at WAL location RECPTR\n"));
printf(_(" -t, --timeline=TLI timeline from which to read log records\n"
printf(_(" -t, --timeline=TLI timeline from which to read WAL records\n"
" (default: 1 or the value used in STARTSEG)\n"));
printf(_(" -V, --version output version information, then exit\n"));
printf(_(" -w, --fullpage only show records with a full page write\n"));