PostgreSQL Source Code  git master
xlog.h
Go to the documentation of this file.
1 /*
2  * xlog.h
3  *
4  * PostgreSQL write-ahead log manager
5  *
6  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
7  * Portions Copyright (c) 1994, Regents of the University of California
8  *
9  * src/include/access/xlog.h
10  */
11 #ifndef XLOG_H
12 #define XLOG_H
13 
14 #include "access/xlogbackup.h"
15 #include "access/xlogdefs.h"
16 #include "datatype/timestamp.h"
17 #include "lib/stringinfo.h"
18 #include "nodes/pg_list.h"
19 
20 
21 /* Sync methods */
23 {
26  WAL_SYNC_METHOD_OPEN, /* for O_SYNC */
28  WAL_SYNC_METHOD_OPEN_DSYNC /* for O_DSYNC */
29 };
30 extern PGDLLIMPORT int wal_sync_method;
31 
35 
36 /* these variables are GUC parameters related to XLOG */
37 extern PGDLLIMPORT int wal_segment_size;
38 extern PGDLLIMPORT int min_wal_size_mb;
39 extern PGDLLIMPORT int max_wal_size_mb;
40 extern PGDLLIMPORT int wal_keep_size_mb;
42 extern PGDLLIMPORT int XLOGbuffers;
45 extern PGDLLIMPORT char *XLogArchiveCommand;
46 extern PGDLLIMPORT bool EnableHotStandby;
47 extern PGDLLIMPORT bool fullPageWrites;
48 extern PGDLLIMPORT bool wal_log_hints;
49 extern PGDLLIMPORT int wal_compression;
50 extern PGDLLIMPORT bool wal_init_zero;
51 extern PGDLLIMPORT bool wal_recycle;
54 extern PGDLLIMPORT bool log_checkpoints;
57 
59 
60 /* Archive modes */
61 typedef enum ArchiveMode
62 {
63  ARCHIVE_MODE_OFF = 0, /* disabled */
64  ARCHIVE_MODE_ON, /* enabled while server is running normally */
65  ARCHIVE_MODE_ALWAYS, /* enabled always (even during recovery) */
67 extern PGDLLIMPORT int XLogArchiveMode;
68 
69 /* WAL levels */
70 typedef enum WalLevel
71 {
76 
77 /* Compression algorithms for WAL */
78 typedef enum WalCompression
79 {
85 
86 /* Recovery states */
87 typedef enum RecoveryState
88 {
89  RECOVERY_STATE_CRASH = 0, /* crash recovery */
90  RECOVERY_STATE_ARCHIVE, /* archive recovery */
91  RECOVERY_STATE_DONE, /* currently in production */
93 
94 extern PGDLLIMPORT int wal_level;
95 
96 /* Is WAL archiving enabled (always or only while server is running normally)? */
97 #define XLogArchivingActive() \
98  (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode > ARCHIVE_MODE_OFF)
99 /* Is WAL archiving enabled always (even during recovery)? */
100 #define XLogArchivingAlways() \
101  (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode == ARCHIVE_MODE_ALWAYS)
102 
103 /*
104  * Is WAL-logging necessary for archival or log-shipping, or can we skip
105  * WAL-logging if we fsync() the data before committing instead?
106  */
107 #define XLogIsNeeded() (wal_level >= WAL_LEVEL_REPLICA)
108 
109 /*
110  * Is a full-page image needed for hint bit updates?
111  *
112  * Normally, we don't WAL-log hint bit updates, but if checksums are enabled,
113  * we have to protect them against torn page writes. When you only set
114  * individual bits on a page, it's still consistent no matter what combination
115  * of the bits make it to disk, but the checksum wouldn't match. Also WAL-log
116  * them if forced by wal_log_hints=on.
117  */
118 #define XLogHintBitIsNeeded() (DataChecksumsEnabled() || wal_log_hints)
119 
120 /* Do we need to WAL-log information required only for Hot Standby and logical replication? */
121 #define XLogStandbyInfoActive() (wal_level >= WAL_LEVEL_REPLICA)
122 
123 /* Do we need to WAL-log information required only for logical replication? */
124 #define XLogLogicalInfoActive() (wal_level >= WAL_LEVEL_LOGICAL)
125 
126 #ifdef WAL_DEBUG
127 extern PGDLLIMPORT bool XLOG_DEBUG;
128 #endif
129 
130 /*
131  * OR-able request flag bits for checkpoints. The "cause" bits are used only
132  * for logging purposes. Note: the flags must be defined so that it's
133  * sensible to OR together request flags arising from different requestors.
134  */
135 
136 /* These directly affect the behavior of CreateCheckPoint and subsidiaries */
137 #define CHECKPOINT_IS_SHUTDOWN 0x0001 /* Checkpoint is for shutdown */
138 #define CHECKPOINT_END_OF_RECOVERY 0x0002 /* Like shutdown checkpoint, but
139  * issued at end of WAL recovery */
140 #define CHECKPOINT_IMMEDIATE 0x0004 /* Do it without delays */
141 #define CHECKPOINT_FORCE 0x0008 /* Force even if no activity */
142 #define CHECKPOINT_FLUSH_ALL 0x0010 /* Flush all pages, including those
143  * belonging to unlogged tables */
144 /* These are important to RequestCheckpoint */
145 #define CHECKPOINT_WAIT 0x0020 /* Wait for completion */
146 #define CHECKPOINT_REQUESTED 0x0040 /* Checkpoint request has been made */
147 /* These indicate the cause of a checkpoint request */
148 #define CHECKPOINT_CAUSE_XLOG 0x0080 /* XLOG consumption */
149 #define CHECKPOINT_CAUSE_TIME 0x0100 /* Elapsed time */
150 
151 /*
152  * Flag bits for the record being inserted, set using XLogSetRecordFlags().
153  */
154 #define XLOG_INCLUDE_ORIGIN 0x01 /* include the replication origin */
155 #define XLOG_MARK_UNIMPORTANT 0x02 /* record not important for durability */
156 
157 
158 /* Checkpoint statistics */
159 typedef struct CheckpointStatsData
160 {
161  TimestampTz ckpt_start_t; /* start of checkpoint */
162  TimestampTz ckpt_write_t; /* start of flushing buffers */
163  TimestampTz ckpt_sync_t; /* start of fsyncs */
164  TimestampTz ckpt_sync_end_t; /* end of fsyncs */
165  TimestampTz ckpt_end_t; /* end of checkpoint */
166 
167  int ckpt_bufs_written; /* # of buffers written */
168 
169  int ckpt_segs_added; /* # of new xlog segments created */
170  int ckpt_segs_removed; /* # of xlog segments deleted */
171  int ckpt_segs_recycled; /* # of xlog segments recycled */
172 
173  int ckpt_sync_rels; /* # of relations synced */
174  uint64 ckpt_longest_sync; /* Longest sync for one relation */
175  uint64 ckpt_agg_sync_time; /* The sum of all the individual sync
176  * times, which is not necessarily the
177  * same as the total elapsed time for the
178  * entire sync phase. */
180 
182 
183 /*
184  * GetWALAvailability return codes
185  */
186 typedef enum WALAvailability
187 {
188  WALAVAIL_INVALID_LSN, /* parameter error */
189  WALAVAIL_RESERVED, /* WAL segment is within max_wal_size */
190  WALAVAIL_EXTENDED, /* WAL segment is reserved by a slot or
191  * wal_keep_size */
192  WALAVAIL_UNRESERVED, /* no longer reserved, but not removed yet */
193  WALAVAIL_REMOVED, /* WAL segment has been removed */
195 
196 struct XLogRecData;
197 struct XLogReaderState;
198 
199 extern XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata,
200  XLogRecPtr fpw_lsn,
201  uint8 flags,
202  int num_fpi,
203  bool topxid_included);
204 extern void XLogFlush(XLogRecPtr record);
205 extern bool XLogBackgroundFlush(void);
206 extern bool XLogNeedsFlush(XLogRecPtr record);
207 extern int XLogFileInit(XLogSegNo logsegno, TimeLineID logtli);
208 extern int XLogFileOpen(XLogSegNo segno, TimeLineID tli);
209 
210 extern void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli);
213 extern void XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN);
215 
216 extern void xlog_redo(struct XLogReaderState *record);
217 extern void xlog_desc(StringInfo buf, struct XLogReaderState *record);
218 extern const char *xlog_identify(uint8 info);
219 
220 extern void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli);
221 
222 extern bool RecoveryInProgress(void);
223 extern RecoveryState GetRecoveryState(void);
224 extern bool XLogInsertAllowed(void);
225 extern XLogRecPtr GetXLogInsertRecPtr(void);
226 extern XLogRecPtr GetXLogWriteRecPtr(void);
227 
228 extern uint64 GetSystemIdentifier(void);
229 extern char *GetMockAuthenticationNonce(void);
230 extern bool DataChecksumsEnabled(void);
232 extern Size XLOGShmemSize(void);
233 extern void XLOGShmemInit(void);
234 extern void BootStrapXLOG(void);
235 extern void InitializeWalConsistencyChecking(void);
236 extern void LocalProcessControlFile(bool reset);
238 extern void StartupXLOG(void);
239 extern void ShutdownXLOG(int code, Datum arg);
240 extern void CreateCheckPoint(int flags);
241 extern bool CreateRestartPoint(int flags);
243 extern void XLogPutNextOid(Oid nextOid);
244 extern XLogRecPtr XLogRestorePoint(const char *rpName);
245 extern void UpdateFullPageWrites(void);
246 extern void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p);
247 extern XLogRecPtr GetRedoRecPtr(void);
248 extern XLogRecPtr GetInsertRecPtr(void);
249 extern XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI);
252 
253 extern void SetWalWriterSleeping(bool sleeping);
254 
255 extern Size WALReadFromBuffers(char *dstbuf, XLogRecPtr startptr, Size count,
256  TimeLineID tli);
257 
258 /*
259  * Routines used by xlogrecovery.c to call back into xlog.c during recovery.
260  */
261 extern void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI);
262 extern bool XLogCheckpointNeeded(XLogSegNo new_segno);
265 extern void SetInstallXLogFileSegmentActive(void);
266 extern bool IsInstallXLogFileSegmentActive(void);
267 extern void XLogShutdownWalRcv(void);
268 
269 /*
270  * Routines to start, stop, and get status of a base backup.
271  */
272 
273 /*
274  * Session-level status of base backups
275  *
276  * This is used in parallel with the shared memory status to control parallel
277  * execution of base backup functions for a given session, be it a backend
278  * dedicated to replication or a normal backend connected to a database. The
279  * update of the session-level status happens at the same time as the shared
280  * memory counters to keep a consistent global and local state of the backups
281  * running.
282  */
283 typedef enum SessionBackupState
284 {
288 
289 extern void do_pg_backup_start(const char *backupidstr, bool fast,
290  List **tablespaces, BackupState *state,
291  StringInfo tblspcmapfile);
292 extern void do_pg_backup_stop(BackupState *state, bool waitforarchive);
293 extern void do_pg_abort_backup(int code, Datum arg);
296 
297 /* File path names (all relative to $PGDATA) */
298 #define RECOVERY_SIGNAL_FILE "recovery.signal"
299 #define STANDBY_SIGNAL_FILE "standby.signal"
300 #define BACKUP_LABEL_FILE "backup_label"
301 #define BACKUP_LABEL_OLD "backup_label.old"
302 
303 #define TABLESPACE_MAP "tablespace_map"
304 #define TABLESPACE_MAP_OLD "tablespace_map.old"
305 
306 /* files to signal promotion to primary */
307 #define PROMOTE_SIGNAL_FILE "promote"
308 
309 #endif /* XLOG_H */
#define PGDLLIMPORT
Definition: c.h:1316
unsigned char uint8
Definition: c.h:504
size_t Size
Definition: c.h:605
int64 TimestampTz
Definition: timestamp.h:39
void * arg
static char * buf
Definition: pg_test_fsync.c:73
uintptr_t Datum
Definition: postgres.h:64
unsigned int Oid
Definition: postgres_ext.h:31
static int fd(const char *x, int i)
Definition: preproc-init.c:105
void reset(void)
Definition: sql-declare.c:600
uint64 ckpt_agg_sync_time
Definition: xlog.h:173
uint64 ckpt_longest_sync
Definition: xlog.h:172
TimestampTz ckpt_start_t
Definition: xlog.h:159
TimestampTz ckpt_end_t
Definition: xlog.h:163
int ckpt_segs_removed
Definition: xlog.h:168
TimestampTz ckpt_write_t
Definition: xlog.h:160
int ckpt_segs_added
Definition: xlog.h:167
TimestampTz ckpt_sync_end_t
Definition: xlog.h:162
TimestampTz ckpt_sync_t
Definition: xlog.h:161
int ckpt_bufs_written
Definition: xlog.h:165
int ckpt_segs_recycled
Definition: xlog.h:169
int ckpt_sync_rels
Definition: xlog.h:171
Definition: pg_list.h:54
DecodedXLogRecord * record
Definition: xlogreader.h:236
XLogRecPtr EndRecPtr
Definition: xlogreader.h:207
Definition: regguts.h:323
int XLogFileInit(XLogSegNo logsegno, TimeLineID logtli)
Definition: xlog.c:3369
uint64 GetSystemIdentifier(void)
Definition: xlog.c:4535
void UpdateFullPageWrites(void)
Definition: xlog.c:8087
bool RecoveryInProgress(void)
Definition: xlog.c:6290
void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p)
Definition: xlog.c:6423
TimeLineID GetWALInsertionTimeLine(void)
Definition: xlog.c:6476
PGDLLIMPORT bool log_checkpoints
Definition: xlog.c:129
void do_pg_abort_backup(int code, Datum arg)
Definition: xlog.c:9314
XLogSegNo XLogGetLastRemovedSegno(void)
Definition: xlog.c:3747
void xlog_desc(StringInfo buf, struct XLogReaderState *record)
Definition: xlogdesc.c:37
Size WALReadFromBuffers(char *dstbuf, XLogRecPtr startptr, Size count, TimeLineID tli)
Definition: xlog.c:1743
XLogRecPtr GetRedoRecPtr(void)
Definition: xlog.c:6393
void SetInstallXLogFileSegmentActive(void)
Definition: xlog.c:9404
XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata, XLogRecPtr fpw_lsn, uint8 flags, int num_fpi, bool topxid_included)
Definition: xlog.c:743
void StartupXLOG(void)
Definition: xlog.c:5388
bool IsInstallXLogFileSegmentActive(void)
Definition: xlog.c:9412
PGDLLIMPORT XLogRecPtr XactLastRecEnd
Definition: xlog.c:254
ArchiveMode
Definition: xlog.h:62
@ ARCHIVE_MODE_ALWAYS
Definition: xlog.h:65
@ ARCHIVE_MODE_OFF
Definition: xlog.h:63
@ ARCHIVE_MODE_ON
Definition: xlog.h:64
bool CreateRestartPoint(int flags)
Definition: xlog.c:7512
PGDLLIMPORT int wal_sync_method
Definition: xlog.c:130
PGDLLIMPORT bool EnableHotStandby
Definition: xlog.c:121
XLogRecPtr GetInsertRecPtr(void)
Definition: xlog.c:6438
SessionBackupState get_backup_status(void)
Definition: xlog.c:9021
void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3716
WALAvailability
Definition: xlog.h:185
@ WALAVAIL_REMOVED
Definition: xlog.h:191
@ WALAVAIL_RESERVED
Definition: xlog.h:187
@ WALAVAIL_UNRESERVED
Definition: xlog.h:190
@ WALAVAIL_EXTENDED
Definition: xlog.h:188
@ WALAVAIL_INVALID_LSN
Definition: xlog.h:186
PGDLLIMPORT CheckpointStatsData CheckpointStats
Definition: xlog.c:209
WALAvailability GetWALAvailability(XLogRecPtr targetLSN)
Definition: xlog.c:7790
PGDLLIMPORT int wal_retrieve_retry_interval
Definition: xlog.c:134
void XLOGShmemInit(void)
Definition: xlog.c:4885
void ShutdownXLOG(int code, Datum arg)
Definition: xlog.c:6539
bool DataChecksumsEnabled(void)
Definition: xlog.c:4555
RecoveryState GetRecoveryState(void)
Definition: xlog.c:6326
char * GetMockAuthenticationNonce(void)
Definition: xlog.c:4545
PGDLLIMPORT int wal_compression
Definition: xlog.c:124
void XLogSetReplicationSlotMinimumLSN(XLogRecPtr lsn)
Definition: xlog.c:2677
void SwitchIntoArchiveRecovery(XLogRecPtr EndRecPtr, TimeLineID replayTLI)
Definition: xlog.c:6165
WalCompression
Definition: xlog.h:79
@ WAL_COMPRESSION_NONE
Definition: xlog.h:80
@ WAL_COMPRESSION_LZ4
Definition: xlog.h:82
@ WAL_COMPRESSION_PGLZ
Definition: xlog.h:81
@ WAL_COMPRESSION_ZSTD
Definition: xlog.h:83
PGDLLIMPORT int wal_decode_buffer_size
Definition: xlog.c:136
XLogRecPtr GetXLogInsertRecPtr(void)
Definition: xlog.c:9355
Size XLOGShmemSize(void)
Definition: xlog.c:4835
void SetWalWriterSleeping(bool sleeping)
Definition: xlog.c:9427
struct CheckpointStatsData CheckpointStatsData
int XLogFileOpen(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3607
XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI)
Definition: xlog.c:6455
WalLevel GetActiveWalLevelOnStandby(void)
Definition: xlog.c:4826
PGDLLIMPORT int CheckPointSegments
Definition: xlog.c:156
void xlog_redo(struct XLogReaderState *record)
Definition: xlog.c:8156
void InitializeWalConsistencyChecking(void)
Definition: xlog.c:4751
PGDLLIMPORT bool fullPageWrites
Definition: xlog.c:122
void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI)
Definition: xlog.c:3929
XLogRecPtr GetLastImportantRecPtr(void)
Definition: xlog.c:6493
PGDLLIMPORT XLogRecPtr ProcLastRecPtr
Definition: xlog.c:253
PGDLLIMPORT char * wal_consistency_checking_string
Definition: xlog.c:125
SessionBackupState
Definition: xlog.h:282
@ SESSION_BACKUP_RUNNING
Definition: xlog.h:284
@ SESSION_BACKUP_NONE
Definition: xlog.h:283
bool XLogNeedsFlush(XLogRecPtr record)
Definition: xlog.c:3122
PGDLLIMPORT int wal_segment_size
Definition: xlog.c:143
void register_persistent_abort_backup_handler(void)
Definition: xlog.c:9341
void ReachedEndOfBackup(XLogRecPtr EndRecPtr, TimeLineID tli)
Definition: xlog.c:6203
void LocalProcessControlFile(bool reset)
Definition: xlog.c:4813
void BootStrapXLOG(void)
Definition: xlog.c:5000
XLogSegNo XLogGetOldestSegno(TimeLineID tli)
Definition: xlog.c:3763
PGDLLIMPORT int XLogArchiveMode
Definition: xlog.c:119
XLogRecPtr GetXLogWriteRecPtr(void)
Definition: xlog.c:9371
PGDLLIMPORT char * XLogArchiveCommand
Definition: xlog.c:120
PGDLLIMPORT int wal_keep_size_mb
Definition: xlog.c:116
bool XLogBackgroundFlush(void)
Definition: xlog.c:2979
PGDLLIMPORT bool * wal_consistency_checking
Definition: xlog.c:126
PGDLLIMPORT int max_slot_wal_keep_size_mb
Definition: xlog.c:135
bool XLogInsertAllowed(void)
Definition: xlog.c:6345
void do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces, BackupState *state, StringInfo tblspcmapfile)
Definition: xlog.c:8712
PGDLLIMPORT bool wal_init_zero
Definition: xlog.c:127
PGDLLIMPORT int min_wal_size_mb
Definition: xlog.c:115
XLogRecPtr XLogRestorePoint(const char *rpName)
Definition: xlog.c:7999
const char * xlog_identify(uint8 info)
Definition: xlogdesc.c:158
PGDLLIMPORT int XLOGbuffers
Definition: xlog.c:117
void do_pg_backup_stop(BackupState *state, bool waitforarchive)
Definition: xlog.c:9040
PGDLLIMPORT bool wal_recycle
Definition: xlog.c:128
WalLevel
Definition: xlog.h:71
@ WAL_LEVEL_REPLICA
Definition: xlog.h:73
@ WAL_LEVEL_LOGICAL
Definition: xlog.h:74
@ WAL_LEVEL_MINIMAL
Definition: xlog.h:72
XLogRecPtr GetFakeLSNForUnloggedRel(void)
Definition: xlog.c:4571
PGDLLIMPORT int XLogArchiveTimeout
Definition: xlog.c:118
void XLogPutNextOid(Oid nextOid)
Definition: xlog.c:7944
void XLogFlush(XLogRecPtr record)
Definition: xlog.c:2791
PGDLLIMPORT XLogRecPtr XactLastCommitEnd
Definition: xlog.c:255
PGDLLIMPORT int wal_level
Definition: xlog.c:131
PGDLLIMPORT bool wal_log_hints
Definition: xlog.c:123
RecoveryState
Definition: xlog.h:88
@ RECOVERY_STATE_CRASH
Definition: xlog.h:89
@ RECOVERY_STATE_DONE
Definition: xlog.h:91
@ RECOVERY_STATE_ARCHIVE
Definition: xlog.h:90
void XLogShutdownWalRcv(void)
Definition: xlog.c:9393
void CreateCheckPoint(int flags)
Definition: xlog.c:6821
void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:8603
PGDLLIMPORT int max_wal_size_mb
Definition: xlog.c:114
void XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN)
Definition: xlog.c:2626
PGDLLIMPORT bool track_wal_io_timing
Definition: xlog.c:137
bool XLogCheckpointNeeded(XLogSegNo new_segno)
Definition: xlog.c:2285
WalSyncMethod
Definition: xlog.h:23
@ WAL_SYNC_METHOD_OPEN
Definition: xlog.h:26
@ WAL_SYNC_METHOD_FDATASYNC
Definition: xlog.h:25
@ WAL_SYNC_METHOD_FSYNC_WRITETHROUGH
Definition: xlog.h:27
@ WAL_SYNC_METHOD_OPEN_DSYNC
Definition: xlog.h:28
@ WAL_SYNC_METHOD_FSYNC
Definition: xlog.h:24
uint64 XLogRecPtr
Definition: xlogdefs.h:21
uint32 TimeLineID
Definition: xlogdefs.h:59
uint64 XLogSegNo
Definition: xlogdefs.h:48