Line data Source code
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-2026, 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/checksum.h"
29 : #include "storage/relfilelocator.h"
30 :
31 :
32 : /*
33 : * Each page of XLOG file has a header like this:
34 : */
35 : #define XLOG_PAGE_MAGIC 0xD11F /* can be used as WAL version indicator */
36 :
37 : typedef struct XLogPageHeaderData
38 : {
39 : uint16 xlp_magic; /* magic value for correctness checks */
40 : uint16 xlp_info; /* flag bits, see below */
41 : TimeLineID xlp_tli; /* TimeLineID of first record on page */
42 : XLogRecPtr xlp_pageaddr; /* XLOG address of this page */
43 :
44 : /*
45 : * When there is not enough space on current page for whole record, we
46 : * continue on the next page. xlp_rem_len is the number of bytes
47 : * remaining from a previous page; it tracks xl_tot_len in the initial
48 : * header. Note that the continuation data isn't necessarily aligned.
49 : */
50 : uint32 xlp_rem_len; /* total len of remaining data for record */
51 : } XLogPageHeaderData;
52 :
53 : #define SizeOfXLogShortPHD MAXALIGN(sizeof(XLogPageHeaderData))
54 :
55 : typedef XLogPageHeaderData *XLogPageHeader;
56 :
57 : /*
58 : * When the XLP_LONG_HEADER flag is set, we store additional fields in the
59 : * page header. (This is ordinarily done just in the first page of an
60 : * XLOG file.) The additional fields serve to identify the file accurately.
61 : */
62 : typedef struct XLogLongPageHeaderData
63 : {
64 : XLogPageHeaderData std; /* standard header fields */
65 : uint64 xlp_sysid; /* system identifier from pg_control */
66 : uint32 xlp_seg_size; /* just as a cross-check */
67 : uint32 xlp_xlog_blcksz; /* just as a cross-check */
68 : } XLogLongPageHeaderData;
69 :
70 : #define SizeOfXLogLongPHD MAXALIGN(sizeof(XLogLongPageHeaderData))
71 :
72 : typedef XLogLongPageHeaderData *XLogLongPageHeader;
73 :
74 : /* When record crosses page boundary, set this flag in new page's header */
75 : #define XLP_FIRST_IS_CONTRECORD 0x0001
76 : /* This flag indicates a "long" page header */
77 : #define XLP_LONG_HEADER 0x0002
78 : /* Replaces a missing contrecord; see CreateOverwriteContrecordRecord */
79 : #define XLP_FIRST_IS_OVERWRITE_CONTRECORD 0x0004
80 : /* All defined flag bits in xlp_info (used for validity checking of header) */
81 : #define XLP_ALL_FLAGS 0x0007
82 :
83 : #define XLogPageHeaderSize(hdr) \
84 : (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)
85 :
86 : /* wal_segment_size can range from 1MB to 1GB */
87 : #define WalSegMinSize 1024 * 1024
88 : #define WalSegMaxSize 1024 * 1024 * 1024
89 : /* default number of min and max wal segments */
90 : #define DEFAULT_MIN_WAL_SEGS 5
91 : #define DEFAULT_MAX_WAL_SEGS 64
92 :
93 : /* check that the given size is a valid wal_segment_size */
94 : #define IsPowerOf2(x) (x > 0 && ((x) & ((x)-1)) == 0)
95 : #define IsValidWalSegSize(size) \
96 : (IsPowerOf2(size) && \
97 : ((size) >= WalSegMinSize && (size) <= WalSegMaxSize))
98 :
99 : #define XLogSegmentsPerXLogId(wal_segsz_bytes) \
100 : (UINT64CONST(0x100000000) / (wal_segsz_bytes))
101 :
102 : #define XLogSegNoOffsetToRecPtr(segno, offset, wal_segsz_bytes, dest) \
103 : (dest) = (segno) * (wal_segsz_bytes) + (offset)
104 :
105 : #define XLogSegmentOffset(xlogptr, wal_segsz_bytes) \
106 : ((xlogptr) & ((wal_segsz_bytes) - 1))
107 :
108 : /*
109 : * Compute a segment number from an XLogRecPtr.
110 : *
111 : * For XLByteToSeg, do the computation at face value. For XLByteToPrevSeg,
112 : * a boundary byte is taken to be in the previous segment. This is suitable
113 : * for deciding which segment to write given a pointer to a record end,
114 : * for example.
115 : */
116 : #define XLByteToSeg(xlrp, logSegNo, wal_segsz_bytes) \
117 : logSegNo = (xlrp) / (wal_segsz_bytes)
118 :
119 : #define XLByteToPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
120 : logSegNo = ((xlrp) - 1) / (wal_segsz_bytes)
121 :
122 : /*
123 : * Convert values of GUCs measured in megabytes to equiv. segment count.
124 : * Rounds down.
125 : */
126 : #define XLogMBVarToSegs(mbvar, wal_segsz_bytes) \
127 : ((mbvar) / ((wal_segsz_bytes) / (1024 * 1024)))
128 :
129 : /*
130 : * Is an XLogRecPtr within a particular XLOG segment?
131 : *
132 : * For XLByteInSeg, do the computation at face value. For XLByteInPrevSeg,
133 : * a boundary byte is taken to be in the previous segment.
134 : */
135 : #define XLByteInSeg(xlrp, logSegNo, wal_segsz_bytes) \
136 : (((xlrp) / (wal_segsz_bytes)) == (logSegNo))
137 :
138 : #define XLByteInPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
139 : ((((xlrp) - 1) / (wal_segsz_bytes)) == (logSegNo))
140 :
141 : /* Check if an XLogRecPtr value is in a plausible range */
142 : #define XRecOffIsValid(xlrp) \
143 : ((xlrp) % XLOG_BLCKSZ >= SizeOfXLogShortPHD)
144 :
145 : /*
146 : * The XLog directory and control file (relative to $PGDATA)
147 : */
148 : #define XLOGDIR "pg_wal"
149 : #define XLOG_CONTROL_FILE "global/pg_control"
150 :
151 : /*
152 : * These macros encapsulate knowledge about the exact layout of XLog file
153 : * names, timeline history file names, and archive-status file names.
154 : */
155 : #define MAXFNAMELEN 64
156 :
157 : /* Length of XLog file name */
158 : #define XLOG_FNAME_LEN 24
159 :
160 : /*
161 : * Generate a WAL segment file name. Do not use this function in a helper
162 : * function allocating the result generated.
163 : */
164 : static inline void
165 36858 : XLogFileName(char *fname, TimeLineID tli, XLogSegNo logSegNo, int wal_segsz_bytes)
166 : {
167 36858 : snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli,
168 36858 : (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
169 36858 : (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)));
170 36858 : }
171 :
172 : static inline void
173 2 : XLogFileNameById(char *fname, TimeLineID tli, uint32 log, uint32 seg)
174 : {
175 2 : snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg);
176 2 : }
177 :
178 : static inline bool
179 30198 : IsXLogFileName(const char *fname)
180 : {
181 50277 : return (strlen(fname) == XLOG_FNAME_LEN && \
182 20079 : strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN);
183 : }
184 :
185 : /*
186 : * XLOG segment with .partial suffix. Used by pg_receivewal and at end of
187 : * archive recovery, when we want to archive a WAL segment but it might not
188 : * be complete yet.
189 : */
190 : static inline bool
191 9010 : IsPartialXLogFileName(const char *fname)
192 : {
193 9017 : return (strlen(fname) == XLOG_FNAME_LEN + strlen(".partial") &&
194 9017 : strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN &&
195 7 : strcmp(fname + XLOG_FNAME_LEN, ".partial") == 0);
196 : }
197 :
198 : static inline void
199 3328 : XLogFromFileName(const char *fname, TimeLineID *tli, XLogSegNo *logSegNo, int wal_segsz_bytes)
200 : {
201 : uint32 log;
202 : uint32 seg;
203 :
204 3328 : sscanf(fname, "%08X%08X%08X", tli, &log, &seg);
205 3328 : *logSegNo = (uint64) log * XLogSegmentsPerXLogId(wal_segsz_bytes) + seg;
206 3328 : }
207 :
208 : static inline void
209 28561 : XLogFilePath(char *path, TimeLineID tli, XLogSegNo logSegNo, int wal_segsz_bytes)
210 : {
211 28561 : snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli,
212 28561 : (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
213 28561 : (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)));
214 28561 : }
215 :
216 : static inline void
217 526 : TLHistoryFileName(char *fname, TimeLineID tli)
218 : {
219 526 : snprintf(fname, MAXFNAMELEN, "%08X.history", tli);
220 526 : }
221 :
222 : static inline bool
223 4362 : IsTLHistoryFileName(const char *fname)
224 : {
225 4377 : return (strlen(fname) == 8 + strlen(".history") &&
226 4377 : strspn(fname, "0123456789ABCDEF") == 8 &&
227 15 : strcmp(fname + 8, ".history") == 0);
228 : }
229 :
230 : static inline void
231 198 : TLHistoryFilePath(char *path, TimeLineID tli)
232 : {
233 198 : snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli);
234 198 : }
235 :
236 : static inline void
237 29183 : StatusFilePath(char *path, const char *xlog, const char *suffix)
238 : {
239 29183 : snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix);
240 29183 : }
241 :
242 : static inline void
243 5 : BackupHistoryFileName(char *fname, TimeLineID tli, XLogSegNo logSegNo, XLogRecPtr startpoint, int wal_segsz_bytes)
244 : {
245 5 : snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli,
246 5 : (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
247 5 : (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)),
248 5 : (uint32) (XLogSegmentOffset(startpoint, wal_segsz_bytes)));
249 5 : }
250 :
251 : static inline bool
252 1351 : IsBackupHistoryFileName(const char *fname)
253 : {
254 1526 : return (strlen(fname) > XLOG_FNAME_LEN &&
255 1526 : strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN &&
256 175 : strcmp(fname + strlen(fname) - strlen(".backup"), ".backup") == 0);
257 : }
258 :
259 : static inline void
260 162 : BackupHistoryFilePath(char *path, TimeLineID tli, XLogSegNo logSegNo, XLogRecPtr startpoint, int wal_segsz_bytes)
261 : {
262 162 : snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli,
263 162 : (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
264 162 : (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)),
265 162 : (uint32) (XLogSegmentOffset((startpoint), wal_segsz_bytes)));
266 162 : }
267 :
268 : /*
269 : * Information logged when we detect a change in one of the parameters
270 : * important for Hot Standby.
271 : */
272 : typedef struct xl_parameter_change
273 : {
274 : int MaxConnections;
275 : int max_worker_processes;
276 : int max_wal_senders;
277 : int max_prepared_xacts;
278 : int max_locks_per_xact;
279 : int wal_level;
280 : bool wal_log_hints;
281 : bool track_commit_timestamp;
282 : } xl_parameter_change;
283 :
284 : /* logs restore point */
285 : typedef struct xl_restore_point
286 : {
287 : TimestampTz rp_time;
288 : char rp_name[MAXFNAMELEN];
289 : } xl_restore_point;
290 :
291 : /* Information logged when data checksum level is changed */
292 : typedef struct xl_checksum_state
293 : {
294 : ChecksumStateType new_checksum_state;
295 : } xl_checksum_state;
296 :
297 : /* Overwrite of prior contrecord */
298 : typedef struct xl_overwrite_contrecord
299 : {
300 : XLogRecPtr overwritten_lsn;
301 : TimestampTz overwrite_time;
302 : } xl_overwrite_contrecord;
303 :
304 : /* End of recovery mark, when we don't do an END_OF_RECOVERY checkpoint */
305 : typedef struct xl_end_of_recovery
306 : {
307 : TimestampTz end_time;
308 : TimeLineID ThisTimeLineID; /* new TLI */
309 : TimeLineID PrevTimeLineID; /* previous TLI we forked off from */
310 : int wal_level;
311 : } xl_end_of_recovery;
312 :
313 : /* checkpoint redo */
314 : typedef struct xl_checkpoint_redo
315 : {
316 : int wal_level;
317 : uint32 data_checksum_version;
318 : } xl_checkpoint_redo;
319 :
320 : /*
321 : * The functions in xloginsert.c construct a chain of XLogRecData structs
322 : * to represent the final WAL record.
323 : */
324 : typedef struct XLogRecData
325 : {
326 : struct XLogRecData *next; /* next struct in chain, or NULL */
327 : const void *data; /* start of rmgr data to include */
328 : uint32 len; /* length of rmgr data to include */
329 : } XLogRecData;
330 :
331 : struct LogicalDecodingContext;
332 : struct XLogRecordBuffer;
333 :
334 : /*
335 : * Method table for resource managers.
336 : *
337 : * This struct must be kept in sync with the PG_RMGR definition in
338 : * rmgr.c.
339 : *
340 : * rm_identify must return a name for the record based on xl_info (without
341 : * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
342 : * "VACUUM". rm_desc can then be called to obtain additional detail for the
343 : * record, if available (e.g. the last block).
344 : *
345 : * rm_mask takes as input a page modified by the resource manager and masks
346 : * out bits that shouldn't be flagged by wal_consistency_checking.
347 : *
348 : * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
349 : * NULL, the corresponding RmgrTable entry is considered invalid.
350 : */
351 : typedef struct RmgrData
352 : {
353 : const char *rm_name;
354 : void (*rm_redo) (XLogReaderState *record);
355 : void (*rm_desc) (StringInfo buf, XLogReaderState *record);
356 : const char *(*rm_identify) (uint8 info);
357 : void (*rm_startup) (void);
358 : void (*rm_cleanup) (void);
359 : void (*rm_mask) (char *pagedata, BlockNumber blkno);
360 : void (*rm_decode) (struct LogicalDecodingContext *ctx,
361 : struct XLogRecordBuffer *buf);
362 : } RmgrData;
363 :
364 : extern PGDLLIMPORT RmgrData RmgrTable[];
365 : extern void RmgrStartup(void);
366 : extern void RmgrCleanup(void);
367 : extern void RmgrNotFound(RmgrId rmid);
368 : extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
369 :
370 : #ifndef FRONTEND
371 : static inline bool
372 7747203 : RmgrIdExists(RmgrId rmid)
373 : {
374 7747203 : return RmgrTable[rmid].rm_name != NULL;
375 : }
376 :
377 : static inline RmgrData
378 7524250 : GetRmgr(RmgrId rmid)
379 : {
380 7524250 : if (unlikely(!RmgrIdExists(rmid)))
381 0 : RmgrNotFound(rmid);
382 7524250 : return RmgrTable[rmid];
383 : }
384 : #endif
385 :
386 : /*
387 : * Exported to support xlog switching from checkpointer
388 : */
389 : extern pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN);
390 : extern XLogRecPtr RequestXLogSwitch(bool mark_unimportant);
391 :
392 : extern void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli);
393 :
394 : extern void XLogRecGetBlockRefInfo(XLogReaderState *record, bool pretty,
395 : bool detailed_format, StringInfo buf,
396 : uint32 *fpi_len);
397 :
398 : /*
399 : * Exported for the functions in timeline.c and xlogarchive.c. Only valid
400 : * in the startup process.
401 : */
402 : extern PGDLLIMPORT bool ArchiveRecoveryRequested;
403 : extern PGDLLIMPORT bool InArchiveRecovery;
404 : extern PGDLLIMPORT bool StandbyMode;
405 : extern PGDLLIMPORT char *recoveryRestoreCommand;
406 :
407 : #endif /* XLOG_INTERNAL_H */
|
