src/include/access/xlog_internal.h

   1 /*
   2  * xlog_internal.h
   3  *
   4  * PostgreSQL write-ahead log internal declarations
   5  *
   6  * NOTE: this file is intended to contain declarations useful for
   7  * manipulating the XLOG files directly, but it is not supposed to be
   8  * needed by rmgr routines (redo support for individual record types).
   9  * So the XLogRecord typedef and associated stuff appear in xlogrecord.h.
  10  *
  11  * Note: This file must be includable in both frontend and backend contexts,
  12  * to allow stand-alone tools like pg_receivewal to deal with WAL files.
  13  *
  14  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
  15  * Portions Copyright (c) 1994, Regents of the University of California
  16  *
  17  * src/include/access/xlog_internal.h
  18  */
  19 #ifndef XLOG_INTERNAL_H
  20 #define XLOG_INTERNAL_H
  21
  22 #include "access/xlogdefs.h"
  23 #include "access/xlogreader.h"
  24 #include "datatype/timestamp.h"
  25 #include "lib/stringinfo.h"
  26 #include "pgtime.h"
  27 #include "storage/block.h"
  28 #include "storage/relfilenode.h"
  29
  30
  31 /*
  32  * Each page of XLOG file has a header like this:
  33  */
  34 #define XLOG_PAGE_MAGIC 0xD10E  /* can be used as WAL version indicator */
  35
  36 typedef struct XLogPageHeaderData
  37 {
  38         uint16          xlp_magic;              /* magic value for correctness checks */
  39         uint16          xlp_info;               /* flag bits, see below */
  40         TimeLineID      xlp_tli;                /* TimeLineID of first record on page */
  41         XLogRecPtr      xlp_pageaddr;   /* XLOG address of this page */
  42
  43         /*
  44          * When there is not enough space on current page for whole record, we
  45          * continue on the next page.  xlp_rem_len is the number of bytes
  46          * remaining from a previous page; it tracks xl_tot_len in the initial
  47          * header.  Note that the continuation data isn't necessarily aligned.
  48          */
  49         uint32          xlp_rem_len;    /* total len of remaining data for record */
  50 } XLogPageHeaderData;
  51
  52 #define SizeOfXLogShortPHD      MAXALIGN(sizeof(XLogPageHeaderData))
  53
  54 typedef XLogPageHeaderData *XLogPageHeader;
  55
  56 /*
  57  * When the XLP_LONG_HEADER flag is set, we store additional fields in the
  58  * page header.  (This is ordinarily done just in the first page of an
  59  * XLOG file.)  The additional fields serve to identify the file accurately.
  60  */
  61 typedef struct XLogLongPageHeaderData
  62 {
  63         XLogPageHeaderData std;         /* standard header fields */
  64         uint64          xlp_sysid;              /* system identifier from pg_control */
  65         uint32          xlp_seg_size;   /* just as a cross-check */
  66         uint32          xlp_xlog_blcksz;        /* just as a cross-check */
  67 } XLogLongPageHeaderData;
  68
  69 #define SizeOfXLogLongPHD       MAXALIGN(sizeof(XLogLongPageHeaderData))
  70
  71 typedef XLogLongPageHeaderData *XLogLongPageHeader;
  72
  73 /* When record crosses page boundary, set this flag in new page's header */
  74 #define XLP_FIRST_IS_CONTRECORD         0x0001
  75 /* This flag indicates a "long" page header */
  76 #define XLP_LONG_HEADER                         0x0002
  77 /* This flag indicates backup blocks starting in this page are optional */
  78 #define XLP_BKP_REMOVABLE                       0x0004
  79 /* Replaces a missing contrecord; see CreateOverwriteContrecordRecord */
  80 #define XLP_FIRST_IS_OVERWRITE_CONTRECORD 0x0008
  81 /* All defined flag bits in xlp_info (used for validity checking of header) */
  82 #define XLP_ALL_FLAGS                           0x000F
  83
  84 #define XLogPageHeaderSize(hdr)         \
  85         (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)
  86
  87 /* wal_segment_size can range from 1MB to 1GB */
  88 #define WalSegMinSize 1024 * 1024
  89 #define WalSegMaxSize 1024 * 1024 * 1024
  90 /* default number of min and max wal segments */
  91 #define DEFAULT_MIN_WAL_SEGS 5
  92 #define DEFAULT_MAX_WAL_SEGS 64
  93
  94 /* check that the given size is a valid wal_segment_size */
  95 #define IsPowerOf2(x) (x > 0 && ((x) & ((x)-1)) == 0)
  96 #define IsValidWalSegSize(size) \
  97          (IsPowerOf2(size) && \
  98          ((size) >= WalSegMinSize && (size) <= WalSegMaxSize))
  99
 100 #define XLogSegmentsPerXLogId(wal_segsz_bytes)  \
 101         (UINT64CONST(0x100000000) / (wal_segsz_bytes))
 102
 103 #define XLogSegNoOffsetToRecPtr(segno, offset, wal_segsz_bytes, dest) \
 104                 (dest) = (segno) * (wal_segsz_bytes) + (offset)
 105
 106 #define XLogSegmentOffset(xlogptr, wal_segsz_bytes)     \
 107         ((xlogptr) & ((wal_segsz_bytes) - 1))
 108
 109 /*
 110  * Compute a segment number from an XLogRecPtr.
 111  *
 112  * For XLByteToSeg, do the computation at face value.  For XLByteToPrevSeg,
 113  * a boundary byte is taken to be in the previous segment.  This is suitable
 114  * for deciding which segment to write given a pointer to a record end,
 115  * for example.
 116  */
 117 #define XLByteToSeg(xlrp, logSegNo, wal_segsz_bytes) \
 118         logSegNo = (xlrp) / (wal_segsz_bytes)
 119
 120 #define XLByteToPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
 121         logSegNo = ((xlrp) - 1) / (wal_segsz_bytes)
 122
 123 /*
 124  * Convert values of GUCs measured in megabytes to equiv. segment count.
 125  * Rounds down.
 126  */
 127 #define XLogMBVarToSegs(mbvar, wal_segsz_bytes) \
 128         ((mbvar) / ((wal_segsz_bytes) / (1024 * 1024)))
 129
 130 /*
 131  * Is an XLogRecPtr within a particular XLOG segment?
 132  *
 133  * For XLByteInSeg, do the computation at face value.  For XLByteInPrevSeg,
 134  * a boundary byte is taken to be in the previous segment.
 135  */
 136 #define XLByteInSeg(xlrp, logSegNo, wal_segsz_bytes) \
 137         (((xlrp) / (wal_segsz_bytes)) == (logSegNo))
 138
 139 #define XLByteInPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
 140         ((((xlrp) - 1) / (wal_segsz_bytes)) == (logSegNo))
 141
 142 /* Check if an XLogRecPtr value is in a plausible range */
 143 #define XRecOffIsValid(xlrp) \
 144                 ((xlrp) % XLOG_BLCKSZ >= SizeOfXLogShortPHD)
 145
 146 /*
 147  * The XLog directory and control file (relative to $PGDATA)
 148  */
 149 #define XLOGDIR                         "pg_wal"
 150 #define XLOG_CONTROL_FILE       "global/pg_control"
 151
 152 /*
 153  * These macros encapsulate knowledge about the exact layout of XLog file
 154  * names, timeline history file names, and archive-status file names.
 155  */
 156 #define MAXFNAMELEN             64
 157
 158 /* Length of XLog file name */
 159 #define XLOG_FNAME_LEN     24
 160
 161 /*
 162  * Generate a WAL segment file name.  Do not use this macro in a helper
 163  * function allocating the result generated.
 164  */
 165 #define XLogFileName(fname, tli, logSegNo, wal_segsz_bytes)     \
 166         snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli,               \
 167                          (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
 168                          (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)))
 169
 170 #define XLogFileNameById(fname, tli, log, seg)  \
 171         snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg)
 172
 173 #define IsXLogFileName(fname) \
 174         (strlen(fname) == XLOG_FNAME_LEN && \
 175          strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN)
 176
 177 /*
 178  * XLOG segment with .partial suffix.  Used by pg_receivewal and at end of
 179  * archive recovery, when we want to archive a WAL segment but it might not
 180  * be complete yet.
 181  */
 182 #define IsPartialXLogFileName(fname)    \
 183         (strlen(fname) == XLOG_FNAME_LEN + strlen(".partial") &&        \
 184          strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN &&         \
 185          strcmp((fname) + XLOG_FNAME_LEN, ".partial") == 0)
 186
 187 #define XLogFromFileName(fname, tli, logSegNo, wal_segsz_bytes) \
 188         do {                                                                                            \
 189                 uint32 log;                                                                             \
 190                 uint32 seg;                                                                             \
 191                 sscanf(fname, "%08X%08X%08X", tli, &log, &seg); \
 192                 *logSegNo = (uint64) log * XLogSegmentsPerXLogId(wal_segsz_bytes) + seg; \
 193         } while (0)
 194
 195 #define XLogFilePath(path, tli, logSegNo, wal_segsz_bytes)      \
 196         snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli, \
 197                          (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
 198                          (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)))
 199
 200 #define TLHistoryFileName(fname, tli)   \
 201         snprintf(fname, MAXFNAMELEN, "%08X.history", tli)
 202
 203 #define IsTLHistoryFileName(fname)      \
 204         (strlen(fname) == 8 + strlen(".history") &&             \
 205          strspn(fname, "0123456789ABCDEF") == 8 &&              \
 206          strcmp((fname) + 8, ".history") == 0)
 207
 208 #define TLHistoryFilePath(path, tli)    \
 209         snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli)
 210
 211 #define StatusFilePath(path, xlog, suffix)      \
 212         snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix)
 213
 214 #define BackupHistoryFileName(fname, tli, logSegNo, startpoint, wal_segsz_bytes) \
 215         snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli, \
 216                          (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
 217                          (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)), \
 218                          (uint32) (XLogSegmentOffset(startpoint, wal_segsz_bytes)))
 219
 220 #define IsBackupHistoryFileName(fname) \
 221         (strlen(fname) > XLOG_FNAME_LEN && \
 222          strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN && \
 223          strcmp((fname) + strlen(fname) - strlen(".backup"), ".backup") == 0)
 224
 225 #define BackupHistoryFilePath(path, tli, logSegNo, startpoint, wal_segsz_bytes) \
 226         snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli, \
 227                          (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
 228                          (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)), \
 229                          (uint32) (XLogSegmentOffset((startpoint), wal_segsz_bytes)))
 230
 231 /*
 232  * Information logged when we detect a change in one of the parameters
 233  * important for Hot Standby.
 234  */
 235 typedef struct xl_parameter_change
 236 {
 237         int                     MaxConnections;
 238         int                     max_worker_processes;
 239         int                     max_wal_senders;
 240         int                     max_prepared_xacts;
 241         int                     max_locks_per_xact;
 242         int                     wal_level;
 243         bool            wal_log_hints;
 244         bool            track_commit_timestamp;
 245 } xl_parameter_change;
 246
 247 /* logs restore point */
 248 typedef struct xl_restore_point
 249 {
 250         TimestampTz rp_time;
 251         char            rp_name[MAXFNAMELEN];
 252 } xl_restore_point;
 253
 254 /* Overwrite of prior contrecord */
 255 typedef struct xl_overwrite_contrecord
 256 {
 257         XLogRecPtr      overwritten_lsn;
 258         TimestampTz overwrite_time;
 259 } xl_overwrite_contrecord;
 260
 261 /* End of recovery mark, when we don't do an END_OF_RECOVERY checkpoint */
 262 typedef struct xl_end_of_recovery
 263 {
 264         TimestampTz end_time;
 265         TimeLineID      ThisTimeLineID; /* new TLI */
 266         TimeLineID      PrevTimeLineID; /* previous TLI we forked off from */
 267 } xl_end_of_recovery;
 268
 269 /*
 270  * The functions in xloginsert.c construct a chain of XLogRecData structs
 271  * to represent the final WAL record.
 272  */
 273 typedef struct XLogRecData
 274 {
 275         struct XLogRecData *next;       /* next struct in chain, or NULL */
 276         char       *data;                       /* start of rmgr data to include */
 277         uint32          len;                    /* length of rmgr data to include */
 278 } XLogRecData;
 279
 280 /*
 281  * Recovery target action.
 282  */
 283 typedef enum
 284 {
 285         RECOVERY_TARGET_ACTION_PAUSE,
 286         RECOVERY_TARGET_ACTION_PROMOTE,
 287         RECOVERY_TARGET_ACTION_SHUTDOWN
 288 }                       RecoveryTargetAction;
 289
 290 /*
 291  * Method table for resource managers.
 292  *
 293  * This struct must be kept in sync with the PG_RMGR definition in
 294  * rmgr.c.
 295  *
 296  * rm_identify must return a name for the record based on xl_info (without
 297  * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
 298  * "VACUUM". rm_desc can then be called to obtain additional detail for the
 299  * record, if available (e.g. the last block).
 300  *
 301  * rm_mask takes as input a page modified by the resource manager and masks
 302  * out bits that shouldn't be flagged by wal_consistency_checking.
 303  *
 304  * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h).
 305  */
 306 typedef struct RmgrData
 307 {
 308         const char *rm_name;
 309         void            (*rm_redo) (XLogReaderState *record);
 310         void            (*rm_desc) (StringInfo buf, XLogReaderState *record);
 311         const char *(*rm_identify) (uint8 info);
 312         void            (*rm_startup) (void);
 313         void            (*rm_cleanup) (void);
 314         void            (*rm_mask) (char *pagedata, BlockNumber blkno);
 315 } RmgrData;
 316
 317 extern const RmgrData RmgrTable[];
 318
 319 /*
 320  * Exported to support xlog switching from checkpointer
 321  */
 322 extern pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN);
 323 extern XLogRecPtr RequestXLogSwitch(bool mark_unimportant);
 324
 325 extern void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli);
 326
 327 /*
 328  * Exported for the functions in timeline.c and xlogarchive.c.  Only valid
 329  * in the startup process.
 330  */
 331 extern bool ArchiveRecoveryRequested;
 332 extern bool InArchiveRecovery;
 333 extern bool StandbyMode;
 334 extern char *recoveryRestoreCommand;
 335
 336 #endif                                                  /* XLOG_INTERNAL_H */