1/*-------------------------------------------------------------------------
4 * Functions for archiving WAL files and restoring from the archive.
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/backend/access/transam/xlogarchive.c
12 *-------------------------------------------------------------------------
36 * Attempt to retrieve the specified file from off-line archival storage.
37 * If successful, fill "path" with its complete path (note that this will be
38 * a temp file name that doesn't follow the normal naming convention), and
41 * If not successful, fill "path" with the name of the normal on-line file
42 * (which may or may not actually exist, but we'll try to use it), and return
45 * For fixed-size files, the caller may pass the expected size as an
46 * additional crosscheck on successful recovery. If the file size is not
47 * known, set expectedSize = 0.
49 * When 'cleanupEnabled' is false, refrain from deleting any old WAL segments
50 * in the archive. This is used when fetching the initial checkpoint record,
51 * when we are not yet sure how far back we need the WAL.
55 const char *recovername, off_t expectedSize,
68 * Ignore restore_command when not in archive recovery (meaning we are in
74 /* In standby mode, restore_command might not be supplied */
79 * When doing archive recovery, we always prefer an archived log file even
80 * if a file of the same name exists in XLOGDIR. The reason is that the
81 * file in XLOGDIR could be an old, un-filled or partly-filled version
82 * that was copied and restored as part of backing up $PGDATA.
84 * We could try to optimize this slightly by checking the local copy
85 * lastchange timestamp against the archived copy, but we have no API to
86 * do this, nor can we guarantee that the lastchange timestamp was
87 * preserved correctly when we copied to archive. Our aim is robustness,
88 * so we elect not to do this.
90 * If we cannot obtain the log file from the archive, however, we will try
91 * to use the XLOGDIR file if it exists. This is so that we can make use
92 * of log segments that weren't yet transferred to the archive.
94 * Notice that we don't actually overwrite any files when we copy back
95 * from archive because the restore_command may inadvertently restore
96 * inappropriate xlogs, or they may be corrupt, so we may wish to fallback
97 * to the segments remaining in current XLOGDIR later. The
98 * copy-from-archive filename is always the same, ensuring that we don't
99 * run out of disk space on long recoveries.
104 * Make sure there is no existing file named recovername.
106 if (
stat(xlogpath, &stat_buf) != 0)
111 errmsg(
"could not stat file \"%s\": %m",
116 if (unlink(xlogpath) != 0)
119 errmsg(
"could not remove file \"%s\": %m",
124 * Calculate the archive file cutoff point for use during log shipping
125 * replication. All files earlier than this point can be deleted from the
126 * archive, though there is no requirement to do so.
128 * If cleanup is not enabled, initialise this with the filename of
129 * InvalidXLogRecPtr, which will prevent the deletion of any WAL files
130 * from the archive because of the alphabetic sorting property of WAL
133 * Once we have successfully located the redo pointer of the checkpoint
134 * from which we start recovery we never request a file prior to the redo
135 * pointer of the last restartpoint. When redo begins we know that we have
136 * successfully located it, so there is no need for additional status
137 * flags to signify the point when we can begin deleting WAL files from
144 XLogFileName(lastRestartPointFname, restartTli, restartSegNo,
146 /* we shouldn't need anything earlier than last restart point */
147 Assert(strcmp(lastRestartPointFname, xlogfname) <= 0);
152 /* Build the restore command to execute */
155 lastRestartPointFname);
165 * PreRestoreCommand() informs the SIGTERM handler for the startup process
166 * that it should proc_exit() right away. This is done for the duration
167 * of the system() call because there isn't a good way to break out while
168 * it is executing. Since we might call proc_exit() in a signal handler,
169 * it is best to put any additional logic before or after the
170 * PreRestoreCommand()/PostRestoreCommand() section.
175 * Copy xlog from archival storage to XLOGDIR
177 rc = system(xlogRestoreCmd);
182 pfree(xlogRestoreCmd);
187 * command apparently succeeded, but let's make sure the file is
188 * really there now and has the correct size.
190 if (
stat(xlogpath, &stat_buf) == 0)
192 if (expectedSize > 0 && stat_buf.
st_size != expectedSize)
197 * If we find a partial file in standby mode, we assume it's
198 * because it's just being copied to the archive, and keep
201 * Otherwise treat a wrong-sized file as FATAL to ensure the
202 * DBA would notice it, but is that too strong? We could try
203 * to plow ahead with a local copy of the file ... but the
204 * problem is that there probably isn't one, and we'd
205 * incorrectly conclude we've reached the end of WAL and we're
206 * done recovering ...
213 (
errmsg(
"archive file \"%s\" has wrong size: %lld instead of %lld",
215 (
long long int) stat_buf.
st_size,
216 (
long long int) expectedSize)));
222 (
errmsg(
"restored log file \"%s\" from archive",
224 strcpy(path, xlogpath);
231 int elevel = (errno == ENOENT) ?
LOG :
FATAL;
235 errmsg(
"could not stat file \"%s\": %m", xlogpath),
236 errdetail(
"\"restore_command\" returned a zero exit status, but stat() failed.")));
241 * Remember, we rollforward UNTIL the restore fails so failure here is
242 * just part of the process... that makes it difficult to determine
243 * whether the restore failed because there isn't an archive to restore,
244 * or because the administrator has specified the restore program
245 * incorrectly. We have to assume the former.
247 * However, if the failure was due to any sort of signal, it's best to
248 * punt and abort recovery. (If we "return false" here, upper levels will
249 * assume that recovery is complete and start up the database!) It's
250 * essential to abort on child SIGINT and SIGQUIT, because per spec
251 * system() ignores SIGINT and SIGQUIT while waiting; if we see one of
252 * those it's a good bet we should have gotten it too.
254 * On SIGTERM, assume we have received a fast shutdown request, and exit
255 * cleanly. It's pure chance whether we receive the SIGTERM first, or the
256 * child process. If we receive it first, the signal handler will call
257 * proc_exit, otherwise we do it here. If we or the child process received
258 * SIGTERM for any other reason than a fast shutdown request, postmaster
259 * will perform an immediate shutdown when it sees us exiting
262 * We treat hard shell errors such as "command not found" as fatal, too.
268 (
errmsg(
"could not restore file \"%s\" from archive: %s",
274 * if an archived file is not available, there might still be a version of
275 * this file in XLOGDIR, so return that as the filename to open.
277 * In many recovery scenarios we expect this to fail also, but if so that
278 * just means we've reached the end of WAL.
285 * Attempt to execute an external shell command during recovery.
287 * 'command' is the shell command to be executed, 'commandName' is a
288 * human-readable name describing the command emitted in the logs. If
289 * 'failOnSignal' is true and the command is killed by a signal, a FATAL
290 * error is thrown. Otherwise a WARNING is emitted.
292 * This is currently used for recovery_end_command and archive_cleanup_command.
296 bool failOnSignal,
uint32 wait_event_info)
298 char *xlogRecoveryCmd;
305 Assert(command && commandName);
308 * Calculate the archive file cutoff point for use during log shipping
309 * replication. All files earlier than this point can be deleted from the
310 * archive, though there is no requirement to do so.
314 XLogFileName(lastRestartPointFname, restartTli, restartSegNo,
318 * construct the command to be executed
326 * execute the constructed command
330 rc = system(xlogRecoveryCmd);
333 pfree(xlogRecoveryCmd);
338 * If the failure was due to any sort of signal, it's best to punt and
339 * abort recovery. See comments in RestoreArchivedFile().
343 translator: First %s represents a postgresql.conf parameter name like
344 "recovery_end_command", the 2nd is the value of that parameter, the
345 third an already translated error message. */
346 (
errmsg(
"%s \"%s\": %s", commandName,
353 * A file was restored from the archive under a temporary filename (path),
354 * and now we want to keep it. Rename it under the permanent filename in
355 * pg_wal (xlogfname), replacing any existing file with the same name.
371 static unsigned int deletedcounter = 1;
374 * On Windows, if another process (e.g a walsender process) holds the
375 * file open in FILE_SHARE_DELETE mode, unlink will succeed, but the
376 * file will still show up in directory listing until the last handle
377 * is closed, and we cannot rename the new file in its place until
378 * that. To avoid that problem, rename the old file to a temporary
379 * name first. Use a counter to create a unique filename, because the
380 * same file might be restored from the archive multiple times, and a
381 * walsender could still be holding onto an old deleted version of it.
389 errmsg(
"could not rename file \"%s\" to \"%s\": %m",
393 /* same-size buffers, so this never truncates */
396 if (unlink(oldpath) != 0)
399 errmsg(
"could not remove file \"%s\": %m",
407 * Create .done file forcibly to prevent the restored segment from being
408 * archived again later.
416 * If the existing file was replaced, since walsenders might have it open,
417 * request them to reload a currently-open segment. This is only required
418 * for WAL segments, walsenders don't hold other files open, but there's
419 * no harm in doing this too often, and we don't know what kind of a file
420 * we're dealing with here.
426 * Signal walsender that new WAL has arrived. Again, this isn't necessary
427 * if we restored something other than a WAL segment, but it does no harm
436 * Create an archive notification file
438 * The name of the notification file is the message that will be picked up
439 * by the archiver, e.g. we write 0000000100000001000000C6.ready
440 * and the archiver then knows to archive XLOGDIR/0000000100000001000000C6,
441 * then when complete, rename it to 0000000100000001000000C6.done
449 /* insert an otherwise empty file called <XLOG>.ready */
456 errmsg(
"could not create archive status file \"%s\": %m",
457 archiveStatusPath)));
464 errmsg(
"could not write archive status file \"%s\": %m",
465 archiveStatusPath)));
470 * Timeline history files are given the highest archival priority to lower
471 * the chance that a promoted standby will choose a timeline that is
472 * already in use. However, the archiver ordinarily tries to gather
473 * multiple files to archive from each scan of the archive_status
474 * directory, which means that newly created timeline history files could
475 * be left unarchived for a while. To ensure that the archiver picks up
476 * timeline history files as soon as possible, we force the archiver to
477 * scan the archive_status directory the next time it looks for a file to
483 /* Notify archiver that it's got something to do */
489 * Convenience routine to notify using segment number representation of filename
503 * XLogArchiveForceDone
505 * Emit notification forcibly that an XLOG segment file has been successfully
506 * archived, by creating <XLOG>.done regardless of whether <XLOG>.ready
514 struct stat stat_buf;
517 /* Exit if already known done */
519 if (
stat(archiveDone, &stat_buf) == 0)
522 /* If .ready exists, rename it to .done */
524 if (
stat(archiveReady, &stat_buf) == 0)
530 /* insert an otherwise empty file called <XLOG>.done */
536 errmsg(
"could not create archive status file \"%s\": %m",
544 errmsg(
"could not write archive status file \"%s\": %m",
551 * XLogArchiveCheckDone
553 * This is called when we are ready to delete or recycle an old XLOG segment
554 * file or backup history file. If it is okay to delete it then return true.
555 * If it is not time to delete it, make sure a .ready file exists, and return
558 * If <XLOG>.done exists, then return true; else if <XLOG>.ready exists,
559 * then return false; else create <XLOG>.ready and return false.
561 * The reason we do things this way is so that if the original attempt to
562 * create <XLOG>.ready fails, we'll retry during subsequent checkpoints.
568 struct stat stat_buf;
570 /* The file is always deletable if archive_mode is "off". */
575 * During archive recovery, the file is deletable if archive_mode is not
583 * At this point of the logic, note that we are either a primary with
584 * archive_mode set to "on" or "always", or a standby with archive_mode
588 /* First check for .done --- this means archiver is done with it */
590 if (
stat(archiveStatusPath, &stat_buf) == 0)
593 /* check for .ready --- this means archiver is still busy with it */
595 if (
stat(archiveStatusPath, &stat_buf) == 0)
598 /* Race condition --- maybe archiver just finished, so recheck */
600 if (
stat(archiveStatusPath, &stat_buf) == 0)
603 /* Retry creation of the .ready file */
611 * Check to see if an XLOG segment file is still unarchived.
612 * This is almost but not quite the inverse of XLogArchiveCheckDone: in
613 * the first place we aren't chartered to recreate the .ready file, and
614 * in the second place we should consider that if the file is already gone
615 * then it's not busy. (This check is needed to handle the race condition
616 * that a checkpoint already deleted the no-longer-needed file.)
622 struct stat stat_buf;
624 /* First check for .done --- this means archiver is done with it */
626 if (
stat(archiveStatusPath, &stat_buf) == 0)
629 /* check for .ready --- this means archiver is still busy with it */
631 if (
stat(archiveStatusPath, &stat_buf) == 0)
634 /* Race condition --- maybe archiver just finished, so recheck */
636 if (
stat(archiveStatusPath, &stat_buf) == 0)
640 * Check to see if the WAL file has been removed by checkpoint, which
641 * implies it has already been archived, and explains why we can't see a
642 * status file for it.
645 if (
stat(archiveStatusPath, &stat_buf) != 0 &&
653 * XLogArchiveIsReadyOrDone
655 * Check to see if an XLOG segment file has a .ready or .done file.
656 * This is similar to XLogArchiveIsBusy(), but returns true if the file
657 * is already archived or is about to be archived.
659 * This is currently only used at recovery. During normal operation this
660 * would be racy: the file might get removed or marked with .ready as we're
661 * checking it, or immediately after we return.
667 struct stat stat_buf;
669 /* First check for .done --- this means archiver is done with it */
671 if (
stat(archiveStatusPath, &stat_buf) == 0)
674 /* check for .ready --- this means archiver is still busy with it */
676 if (
stat(archiveStatusPath, &stat_buf) == 0)
679 /* Race condition --- maybe archiver just finished, so recheck */
681 if (
stat(archiveStatusPath, &stat_buf) == 0)
690 * Check to see if an XLOG segment file has an archive notification (.ready)
697 struct stat stat_buf;
700 if (
stat(archiveStatusPath, &stat_buf) == 0)
709 * Cleanup archive notification file(s) for a particular xlog segment
716 /* Remove the .done file */
718 unlink(archiveStatusPath);
719 /* should we complain about failure? */
721 /* Remove the .ready file if present --- normally it shouldn't be */
723 unlink(archiveStatusPath);
724 /* should we complain about failure? */
void PreRestoreCommand(void)
void PostRestoreCommand(void)
char * BuildRestoreCommand(const char *restoreCommand, const char *xlogpath, const char *xlogfname, const char *lastRestartPointFname)
int errmsg_internal(const char *fmt,...)
int errcode_for_file_access(void)
int errdetail(const char *fmt,...)
int errmsg(const char *fmt,...)
#define ereport(elevel,...)
int durable_rename(const char *oldfile, const char *newfile, int elevel)
FILE * AllocateFile(const char *name, const char *mode)
Assert(PointerIsAligned(start, uint64))
void pfree(void *pointer)
static char xlogfpath[MAXPGPATH]
char * replace_percent_placeholders(const char *instr, const char *param_name, const char *letters,...)
void PgArchForceDirScan(void)
size_t strlcpy(char *dst, const char *src, size_t siz)
static int fd(const char *x, int i)
char * wait_result_to_str(int exitstatus)
bool wait_result_is_signal(int exit_status, int signum)
bool wait_result_is_any_signal(int exit_status, bool include_command_not_found)
static void pgstat_report_wait_start(uint32 wait_event_info)
static void pgstat_report_wait_end(void)
void WalSndWakeup(bool physical, bool logical)
void WalSndRqstFileReload(void)
RecoveryState GetRecoveryState(void)
void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli)
#define XLogArchivingActive()
#define XLogArchivingAlways()
static bool IsTLHistoryFileName(const char *fname)
static void StatusFilePath(char *path, const char *xlog, const char *suffix)
#define XLByteToSeg(xlrp, logSegNo, wal_segsz_bytes)
static void XLogFileName(char *fname, TimeLineID tli, XLogSegNo logSegNo, int wal_segsz_bytes)
void XLogArchiveForceDone(const char *xlog)
bool XLogArchiveIsReadyOrDone(const char *xlog)
bool XLogArchiveIsBusy(const char *xlog)
bool XLogArchiveIsReady(const char *xlog)
void XLogArchiveNotifySeg(XLogSegNo segno, TimeLineID tli)
void ExecuteRecoveryCommand(const char *command, const char *commandName, bool failOnSignal, uint32 wait_event_info)
bool XLogArchiveCheckDone(const char *xlog)
bool RestoreArchivedFile(char *path, const char *xlogfname, const char *recovername, off_t expectedSize, bool cleanupEnabled)
void XLogArchiveNotify(const char *xlog)
void KeepFileRestoredFromArchive(const char *path, const char *xlogfname)
void XLogArchiveCleanup(const char *xlog)
bool ArchiveRecoveryRequested
char * recoveryRestoreCommand