Quelle  timeline.c

/*-------------------------------------------------------------------------
 *
 * timeline.c
 *  Functions for reading and writing timeline history files.
 *
 * A timeline history file lists the timeline changes of the timeline, in
 * a simple text format. They are archived along with the WAL segments.
 *
 * The files are named like "<tli>.history". For example, if the database
 * starts up and switches to timeline 5, the timeline history file would be
 * called "00000005.history".
 *
 * Each line in the file represents a timeline switch:
 *
 * <parentTLI> <switchpoint> <reason>
 *
 * parentTLI ID of the parent timeline
 * switchpoint XLogRecPtr of the WAL location where the switch happened
 * reason  human-readable explanation of why the timeline was changed
 *
 * The fields are separated by tabs. Lines beginning with # are comments, and
 * are ignored. Empty lines are also ignored.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/backend/access/transam/timeline.c
 *
 *-------------------------------------------------------------------------
 */

#include "postgres.h"

#include <sys/stat.h>
#include <unistd.h>

#include "access/timeline.h"
#include "access/xlog.h"
#include "access/xlog_internal.h"
#include "access/xlogarchive.h"
#include "access/xlogdefs.h"
#include "pgstat.h"
#include "storage/fd.h"

/*
 * Copies all timeline history files with id's between 'begin' and 'end'
 * from archive to pg_wal.
 */
void
restoreTimeLineHistoryFiles(TimeLineID begin, TimeLineID end)
{
 char  path[MAXPGPATH];
 char  histfname[MAXFNAMELEN];
 TimeLineID tli;

 for (tli = begin; tli < end; tli++)
 {
  if (tli == 1)
   continue;

  TLHistoryFileName(histfname, tli);
  if (RestoreArchivedFile(path, histfname, "RECOVERYHISTORY", 0, false))
   KeepFileRestoredFromArchive(path, histfname);
 }
}

/*
 * Try to read a timeline's history file.
 *
 * If successful, return the list of component TLIs (the given TLI followed by
 * its ancestor TLIs).  If we can't find the history file, assume that the
 * timeline has no parents, and return a list of just the specified timeline
 * ID.
 */
List *
readTimeLineHistory(TimeLineID targetTLI)
{
 List    *result;
 char  path[MAXPGPATH];
 char  histfname[MAXFNAMELEN];
 FILE    *fd;
 TimeLineHistoryEntry *entry;
 TimeLineID lasttli = 0;
 XLogRecPtr prevend;
 bool  fromArchive = false;

 /* Timeline 1 does not have a history file, so no need to check */
 if (targetTLI == 1)
 {
  entry = (TimeLineHistoryEntry *) palloc(sizeof(TimeLineHistoryEntry));
  entry->tli = targetTLI;
  entry->begin = entry->end = InvalidXLogRecPtr;
  return list_make1(entry);
 }

 if (ArchiveRecoveryRequested)
 {
  TLHistoryFileName(histfname, targetTLI);
  fromArchive =
   RestoreArchivedFile(path, histfname, "RECOVERYHISTORY", 0, false);
 }
 else
  TLHistoryFilePath(path, targetTLI);

 fd = AllocateFile(path, "r");
 if (fd == NULL)
 {
  if (errno != ENOENT)
   ereport(FATAL,
     (errcode_for_file_access(),
      errmsg("could not open file \"%s\": %m", path)));
  /* Not there, so assume no parents */
  entry = (TimeLineHistoryEntry *) palloc(sizeof(TimeLineHistoryEntry));
  entry->tli = targetTLI;
  entry->begin = entry->end = InvalidXLogRecPtr;
  return list_make1(entry);
 }

 result = NIL;

 /*
  * Parse the file...
 */
 prevend = InvalidXLogRecPtr;
 for (;;)
 {
  char  fline[MAXPGPATH];
  char    *res;
  char    *ptr;
  TimeLineID tli;
  uint32  switchpoint_hi;
  uint32  switchpoint_lo;
  int   nfields;

  pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_READ);
  res = fgets(fline, sizeof(fline), fd);
  pgstat_report_wait_end();
  if (res == NULL)
  {
   if (ferror(fd))
    ereport(ERROR,
      (errcode_for_file_access(),
       errmsg("could not read file \"%s\": %m", path)));

   break;
  }

  /* skip leading whitespace and check for # comment */
  for (ptr = fline; *ptr; ptr++)
  {
   if (!isspace((unsigned char) *ptr))
    break;
  }
  if (*ptr == '\0' || *ptr == '#')
   continue;

  nfields = sscanf(fline, "%u\t%X/%X", &tli, &switchpoint_hi, &switchpoint_lo);

  if (nfields < 1)
  {
   /* expect a numeric timeline ID as first field of line */
   ereport(FATAL,
     (errmsg("syntax error in history file: %s", fline),
      errhint("Expected a numeric timeline ID.")));
  }
  if (nfields != 3)
   ereport(FATAL,
     (errmsg("syntax error in history file: %s", fline),
      errhint("Expected a write-ahead log switchpoint location.")));

  if (result && tli <= lasttli)
   ereport(FATAL,
     (errmsg("invalid data in history file: %s", fline),
      errhint("Timeline IDs must be in increasing sequence.")));

  lasttli = tli;

  entry = (TimeLineHistoryEntry *) palloc(sizeof(TimeLineHistoryEntry));
  entry->tli = tli;
  entry->begin = prevend;
  entry->end = ((uint64) (switchpoint_hi)) << 32 | (uint64) switchpoint_lo;
  prevend = entry->end;

  /* Build list with newest item first */
  result = lcons(entry, result);

  /* we ignore the remainder of each line */
 }

 FreeFile(fd);

 if (result && targetTLI <= lasttli)
  ereport(FATAL,
    (errmsg("invalid data in history file \"%s\"", path),
     errhint("Timeline IDs must be less than child timeline's ID.")));

 /*
  * Create one more entry for the "tip" of the timeline, which has no entry
  * in the history file.
 */
 entry = (TimeLineHistoryEntry *) palloc(sizeof(TimeLineHistoryEntry));
 entry->tli = targetTLI;
 entry->begin = prevend;
 entry->end = InvalidXLogRecPtr;

 result = lcons(entry, result);

 /*
  * If the history file was fetched from archive, save it in pg_wal for
  * future reference.
 */
 if (fromArchive)
  KeepFileRestoredFromArchive(path, histfname);

 return result;
}

/*
 * Probe whether a timeline history file exists for the given timeline ID
 */
bool
existsTimeLineHistory(TimeLineID probeTLI)
{
 char  path[MAXPGPATH];
 char  histfname[MAXFNAMELEN];
 FILE    *fd;

 /* Timeline 1 does not have a history file, so no need to check */
 if (probeTLI == 1)
  return false;

 if (ArchiveRecoveryRequested)
 {
  TLHistoryFileName(histfname, probeTLI);
  RestoreArchivedFile(path, histfname, "RECOVERYHISTORY", 0, false);
 }
 else
  TLHistoryFilePath(path, probeTLI);

 fd = AllocateFile(path, "r");
 if (fd != NULL)
 {
  FreeFile(fd);
  return true;
 }
 else
 {
  if (errno != ENOENT)
   ereport(FATAL,
     (errcode_for_file_access(),
      errmsg("could not open file \"%s\": %m", path)));
  return false;
 }
}

/*
 * Find the newest existing timeline, assuming that startTLI exists.
 *
 * Note: while this is somewhat heuristic, it does positively guarantee
 * that (result + 1) is not a known timeline, and therefore it should
 * be safe to assign that ID to a new timeline.
 */
TimeLineID
findNewestTimeLine(TimeLineID startTLI)
{
 TimeLineID newestTLI;
 TimeLineID probeTLI;

 /*
  * The algorithm is just to probe for the existence of timeline history
  * files.  XXX is it useful to allow gaps in the sequence?
 */
 newestTLI = startTLI;

 for (probeTLI = startTLI + 1;; probeTLI++)
 {
  if (existsTimeLineHistory(probeTLI))
  {
   newestTLI = probeTLI; /* probeTLI exists */
  }
  else
  {
   /* doesn't exist, assume we're done */
   break;
  }
 }

 return newestTLI;
}

/*
 * Create a new timeline history file.
 *
 * newTLI: ID of the new timeline
 * parentTLI: ID of its immediate parent
 * switchpoint: WAL location where the system switched to the new timeline
 * reason: human-readable explanation of why the timeline was switched
 *
 * Currently this is only used at the end recovery, and so there are no locking
 * considerations.  But we should be just as tense as XLogFileInit to avoid
 * emplacing a bogus file.
 */
void
writeTimeLineHistory(TimeLineID newTLI, TimeLineID parentTLI,
      XLogRecPtr switchpoint, char *reason)
{
 char  path[MAXPGPATH];
 char  tmppath[MAXPGPATH];
 char  histfname[MAXFNAMELEN];
 char  buffer[BLCKSZ];
 int   srcfd;
 int   fd;
 int   nbytes;

 Assert(newTLI > parentTLI); /* else bad selection of newTLI */

 /*
  * Write into a temp file name.
 */
 snprintf(tmppath, MAXPGPATH, XLOGDIR "/xlogtemp.%d", (int) getpid());

 unlink(tmppath);

 /* do not use get_sync_bit() here --- want to fsync only at end of fill */
 fd = OpenTransientFile(tmppath, O_RDWR | O_CREAT | O_EXCL);
 if (fd < 0)
  ereport(ERROR,
    (errcode_for_file_access(),
     errmsg("could not create file \"%s\": %m", tmppath)));

 /*
  * If a history file exists for the parent, copy it verbatim
 */
 if (ArchiveRecoveryRequested)
 {
  TLHistoryFileName(histfname, parentTLI);
  RestoreArchivedFile(path, histfname, "RECOVERYHISTORY", 0, false);
 }
 else
  TLHistoryFilePath(path, parentTLI);

 srcfd = OpenTransientFile(path, O_RDONLY);
 if (srcfd < 0)
 {
  if (errno != ENOENT)
   ereport(ERROR,
     (errcode_for_file_access(),
      errmsg("could not open file \"%s\": %m", path)));
  /* Not there, so assume parent has no parents */
 }
 else
 {
  for (;;)
  {
   errno = 0;
   pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_READ);
   nbytes = (int) read(srcfd, buffer, sizeof(buffer));
   pgstat_report_wait_end();
   if (nbytes < 0 || errno != 0)
    ereport(ERROR,
      (errcode_for_file_access(),
       errmsg("could not read file \"%s\": %m", path)));
   if (nbytes == 0)
    break;
   errno = 0;
   pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_WRITE);
   if ((int) write(fd, buffer, nbytes) != nbytes)
   {
    int   save_errno = errno;

    /*
     * If we fail to make the file, delete it to release disk
     * space
 */
    unlink(tmppath);

    /*
     * if write didn't set errno, assume problem is no disk space
 */
    errno = save_errno ? save_errno : ENOSPC;

    ereport(ERROR,
      (errcode_for_file_access(),
       errmsg("could not write to file \"%s\": %m", tmppath)));
   }
   pgstat_report_wait_end();
  }

  if (CloseTransientFile(srcfd) != 0)
   ereport(ERROR,
     (errcode_for_file_access(),
      errmsg("could not close file \"%s\": %m", path)));
 }

 /*
  * Append one line with the details of this timeline split.
  *
  * If we did have a parent file, insert an extra newline just in case the
  * parent file failed to end with one.
 */
 snprintf(buffer, sizeof(buffer),
    "%s%u\t%X/%X\t%s\n",
    (srcfd < 0) ? "" : "\n",
    parentTLI,
    LSN_FORMAT_ARGS(switchpoint),
    reason);

 nbytes = strlen(buffer);
 errno = 0;
 pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_WRITE);
 if ((int) write(fd, buffer, nbytes) != nbytes)
 {
  int   save_errno = errno;

  /*
   * If we fail to make the file, delete it to release disk space
 */
  unlink(tmppath);
  /* if write didn't set errno, assume problem is no disk space */
  errno = save_errno ? save_errno : ENOSPC;

  ereport(ERROR,
    (errcode_for_file_access(),
     errmsg("could not write to file \"%s\": %m", tmppath)));
 }
 pgstat_report_wait_end();

 pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_SYNC);
 if (pg_fsync(fd) != 0)
  ereport(data_sync_elevel(ERROR),
    (errcode_for_file_access(),
     errmsg("could not fsync file \"%s\": %m", tmppath)));
 pgstat_report_wait_end();

 if (CloseTransientFile(fd) != 0)
  ereport(ERROR,
    (errcode_for_file_access(),
     errmsg("could not close file \"%s\": %m", tmppath)));

 /*
  * Now move the completed history file into place with its final name.
 */
 TLHistoryFilePath(path, newTLI);
 Assert(access(path, F_OK) != 0 && errno == ENOENT);
 durable_rename(tmppath, path, ERROR);

 /* The history file can be archived immediately. */
 if (XLogArchivingActive())
 {
  TLHistoryFileName(histfname, newTLI);
  XLogArchiveNotify(histfname);
 }
}

/*
 * Writes a history file for given timeline and contents.
 *
 * Currently this is only used in the walreceiver process, and so there are
 * no locking considerations.  But we should be just as tense as XLogFileInit
 * to avoid emplacing a bogus file.
 */
void
writeTimeLineHistoryFile(TimeLineID tli, char *content, int size)
{
 char  path[MAXPGPATH];
 char  tmppath[MAXPGPATH];
 int   fd;

 /*
  * Write into a temp file name.
 */
 snprintf(tmppath, MAXPGPATH, XLOGDIR "/xlogtemp.%d", (int) getpid());

 unlink(tmppath);

 /* do not use get_sync_bit() here --- want to fsync only at end of fill */
 fd = OpenTransientFile(tmppath, O_RDWR | O_CREAT | O_EXCL);
 if (fd < 0)
  ereport(ERROR,
    (errcode_for_file_access(),
     errmsg("could not create file \"%s\": %m", tmppath)));

 errno = 0;
 pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_FILE_WRITE);
 if ((int) write(fd, content, size) != size)
 {
  int   save_errno = errno;

  /*
   * If we fail to make the file, delete it to release disk space
 */
  unlink(tmppath);
  /* if write didn't set errno, assume problem is no disk space */
  errno = save_errno ? save_errno : ENOSPC;

  ereport(ERROR,
    (errcode_for_file_access(),
     errmsg("could not write to file \"%s\": %m", tmppath)));
 }
 pgstat_report_wait_end();

 pgstat_report_wait_start(WAIT_EVENT_TIMELINE_HISTORY_FILE_SYNC);
 if (pg_fsync(fd) != 0)
  ereport(data_sync_elevel(ERROR),
    (errcode_for_file_access(),
     errmsg("could not fsync file \"%s\": %m", tmppath)));
 pgstat_report_wait_end();

 if (CloseTransientFile(fd) != 0)
  ereport(ERROR,
    (errcode_for_file_access(),
     errmsg("could not close file \"%s\": %m", tmppath)));

 /*
  * Now move the completed history file into place with its final name,
  * replacing any existing file with the same name.
 */
 TLHistoryFilePath(path, tli);
 durable_rename(tmppath, path, ERROR);
}

/*
 * Returns true if 'expectedTLEs' contains a timeline with id 'tli'
 */
bool
tliInHistory(TimeLineID tli, List *expectedTLEs)
{
 ListCell   *cell;

 foreach(cell, expectedTLEs)
 {
  if (((TimeLineHistoryEntry *) lfirst(cell))->tli == tli)
   return true;
 }

 return false;
}

/*
 * Returns the ID of the timeline in use at a particular point in time, in
 * the given timeline history.
 */
TimeLineID
tliOfPointInHistory(XLogRecPtr ptr, List *history)
{
 ListCell   *cell;

 foreach(cell, history)
 {
  TimeLineHistoryEntry *tle = (TimeLineHistoryEntry *) lfirst(cell);

  if ((XLogRecPtrIsInvalid(tle->begin) || tle->begin <= ptr) &&
   (XLogRecPtrIsInvalid(tle->end) || ptr < tle->end))
  {
   /* found it */
   return tle->tli;
  }
 }

 /* shouldn't happen. */
 elog(ERROR, "timeline history was not contiguous");
 return 0;     /* keep compiler quiet */
}

/*
 * Returns the point in history where we branched off the given timeline,
 * and the timeline we branched to (*nextTLI). Returns InvalidXLogRecPtr if
 * the timeline is current, ie. we have not branched off from it, and throws
 * an error if the timeline is not part of this server's history.
 */
XLogRecPtr
tliSwitchPoint(TimeLineID tli, List *history, TimeLineID *nextTLI)
{
 ListCell   *cell;

 if (nextTLI)
  *nextTLI = 0;
 foreach(cell, history)
 {
  TimeLineHistoryEntry *tle = (TimeLineHistoryEntry *) lfirst(cell);

  if (tle->tli == tli)
   return tle->end;
  if (nextTLI)
   *nextTLI = tle->tli;
 }

 ereport(ERROR,
   (errmsg("requested timeline %u is not in this server's history",
     tli)));
 return InvalidXLogRecPtr; /* keep compiler quiet */
}