From 0e662610e1335a16529d9da6bb45cd9d410faa45 Mon Sep 17 00:00:00 2001 From: Bharath Rupireddy Date: Wed, 20 Jul 2022 11:53:03 +0000 Subject: [PATCH v7] Consistently use "WAL file(s)" in docs Authors: Kyotaro Horiguchi, Bharath Rupireddy --- doc/src/sgml/backup.sgml | 14 ++--- doc/src/sgml/config.sgml | 4 +- doc/src/sgml/ref/pg_waldump.sgml | 10 ++-- doc/src/sgml/wal.sgml | 60 +++++++++---------- src/backend/utils/misc/postgresql.conf.sample | 8 +-- 5 files changed, 48 insertions(+), 48 deletions(-) diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml index 73a774d3d7..cc5ae59ac2 100644 --- a/doc/src/sgml/backup.sgml +++ b/doc/src/sgml/backup.sgml @@ -1095,7 +1095,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 pg_wal - subdirectory, as it might contain logs which + subdirectory, as it might contain WAL files which were not archived before the system went down. @@ -1173,8 +1173,8 @@ SELECT * FROM pg_backup_stop(wait_for_archive => true); which tells PostgreSQL how to retrieve archived WAL file segments. Like the archive_command, this is a shell command string. It can contain %f, which is - replaced by the name of the desired log file, and %p, - which is replaced by the path name to copy the log file to. + replaced by the name of the desired WAL file, and %p, + 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 %% if you need to embed an actual % @@ -1462,9 +1462,9 @@ archive_command = 'local_backup_script.sh "%p" "%f"' CREATE TABLESPACE 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 @@ -1481,11 +1481,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 parameter. (Read the notes and warnings in 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 full_page_writes is on. In the meantime, administrators might wish to reduce the number diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 37fd80388c..8275e557ef 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -4228,7 +4228,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows - Specifies the minimum size of past log file segments kept in the + Specifies the minimum size of past WAL files kept in the pg_wal directory, in case a standby server needs to fetch them for streaming replication. If a standby @@ -4821,7 +4821,7 @@ ANY num_sync ( startseg - 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. @@ -63,7 +63,7 @@ PostgreSQL documentation endseg - Stop after reading the specified log segment file. + Stop after reading the specified WAL segment file. @@ -141,7 +141,7 @@ PostgreSQL documentation - 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 pg_wal subdirectory that contains such files. The default is to search in the current directory, the pg_wal subdirectory of the @@ -203,7 +203,7 @@ PostgreSQL documentation 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. @@ -213,7 +213,7 @@ PostgreSQL documentation - 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 startseg, if that is specified; otherwise, the default is 1. diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml index 01f7379ebb..30842c0396 100644 --- a/doc/src/sgml/wal.sgml +++ b/doc/src/sgml/wal.sgml @@ -297,12 +297,12 @@ transaction processing. Briefly, WAL'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.) @@ -323,15 +323,15 @@ Using WAL 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 fsync of the log file may + transactions, one fsync of the WAL file may suffice to commit many transactions. @@ -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 — 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. @@ -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 WAL 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 - WAL archiving is being done, the log segments must be + WAL archiving is being done, the WAL segments must be archived before being recycled or removed.) @@ -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. @@ -614,10 +614,10 @@ The number of WAL segment files in pg_wal directory depends on min_wal_size, max_wal_size 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, max_wal_size is + short-term peak of WAL output rate, max_wal_size 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 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 pg_wal + and then recycles any old WAL segment files in the pg_wal 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 WAL 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, WAL buffers should be written and flushed by an XLogFlush 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, XLogFlush requests might + with high WAL output, XLogFlush requests might not occur often enough to prevent XLogInsertRecord from having to do writes. On such systems one should increase the number of WAL buffers by @@ -724,7 +724,7 @@ commit_delay, so this value is recommended as the starting point to use when optimizing for a particular workload. While tuning commit_delay 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 @@ WAL is automatically enabled; no action is required from the administrator except ensuring that the - disk-space requirements for the WAL logs are met, + disk-space requirements for the WAL files are met, and that any necessary tuning is done (see ). WAL records are appended to the WAL - 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 (LSN) that is a byte offset into - the logs, increasing monotonically with each new record. + the WAL, increasing monotonically with each new record. LSN values are returned as the datatype pg_lsn. Values can be compared to calculate the volume of WAL data that @@ -846,12 +846,12 @@ - WAL logs are stored in the directory + 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 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 log record headers + configure option). The WAL record headers are described in access/xlogrecord.h; 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 @@ - 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 pg_wal 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 PostgreSQL's - WAL log files do not make such false reports. + WAL files do not make such false reports. (See .) - 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 pg_control. Therefore, at the start of recovery, the server first reads pg_control 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 is not disabled), all pages changed since the checkpoint will be restored to a consistent state. @@ -897,7 +897,7 @@ To deal with the case where pg_control 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 — newest to oldest — in order to find the latest checkpoint. This has not been implemented yet. pg_control is small enough (less than one disk page) diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample index b4bc06e5f5..6bb37cbecf 100644 --- a/src/backend/utils/misc/postgresql.conf.sample +++ b/src/backend/utils/misc/postgresql.conf.sample @@ -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.25.1