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-2023, 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 */
22 #define SYNC_METHOD_FSYNC 0
23 #define SYNC_METHOD_FDATASYNC 1
24 #define SYNC_METHOD_OPEN 2 /* for O_SYNC */
25 #define SYNC_METHOD_FSYNC_WRITETHROUGH 3
26 #define SYNC_METHOD_OPEN_DSYNC 4 /* for O_DSYNC */
27 extern PGDLLIMPORT int sync_method;
28 
32 
33 /* these variables are GUC parameters related to XLOG */
34 extern PGDLLIMPORT int wal_segment_size;
35 extern PGDLLIMPORT int min_wal_size_mb;
36 extern PGDLLIMPORT int max_wal_size_mb;
37 extern PGDLLIMPORT int wal_keep_size_mb;
39 extern PGDLLIMPORT int XLOGbuffers;
42 extern PGDLLIMPORT char *XLogArchiveCommand;
43 extern PGDLLIMPORT bool EnableHotStandby;
44 extern PGDLLIMPORT bool fullPageWrites;
45 extern PGDLLIMPORT bool wal_log_hints;
46 extern PGDLLIMPORT int wal_compression;
47 extern PGDLLIMPORT bool wal_init_zero;
48 extern PGDLLIMPORT bool wal_recycle;
51 extern PGDLLIMPORT bool log_checkpoints;
54 
56 
57 /* Archive modes */
58 typedef enum ArchiveMode
59 {
60  ARCHIVE_MODE_OFF = 0, /* disabled */
61  ARCHIVE_MODE_ON, /* enabled while server is running normally */
62  ARCHIVE_MODE_ALWAYS /* enabled always (even during recovery) */
64 extern PGDLLIMPORT int XLogArchiveMode;
65 
66 /* WAL levels */
67 typedef enum WalLevel
68 {
73 
74 /* Compression algorithms for WAL */
75 typedef enum WalCompression
76 {
82 
83 /* Recovery states */
84 typedef enum RecoveryState
85 {
86  RECOVERY_STATE_CRASH = 0, /* crash recovery */
87  RECOVERY_STATE_ARCHIVE, /* archive recovery */
88  RECOVERY_STATE_DONE /* currently in production */
90 
91 extern PGDLLIMPORT int wal_level;
92 
93 /* Is WAL archiving enabled (always or only while server is running normally)? */
94 #define XLogArchivingActive() \
95  (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode > ARCHIVE_MODE_OFF)
96 /* Is WAL archiving enabled always (even during recovery)? */
97 #define XLogArchivingAlways() \
98  (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode == ARCHIVE_MODE_ALWAYS)
99 
100 /*
101  * Is WAL-logging necessary for archival or log-shipping, or can we skip
102  * WAL-logging if we fsync() the data before committing instead?
103  */
104 #define XLogIsNeeded() (wal_level >= WAL_LEVEL_REPLICA)
105 
106 /*
107  * Is a full-page image needed for hint bit updates?
108  *
109  * Normally, we don't WAL-log hint bit updates, but if checksums are enabled,
110  * we have to protect them against torn page writes. When you only set
111  * individual bits on a page, it's still consistent no matter what combination
112  * of the bits make it to disk, but the checksum wouldn't match. Also WAL-log
113  * them if forced by wal_log_hints=on.
114  */
115 #define XLogHintBitIsNeeded() (DataChecksumsEnabled() || wal_log_hints)
116 
117 /* Do we need to WAL-log information required only for Hot Standby and logical replication? */
118 #define XLogStandbyInfoActive() (wal_level >= WAL_LEVEL_REPLICA)
119 
120 /* Do we need to WAL-log information required only for logical replication? */
121 #define XLogLogicalInfoActive() (wal_level >= WAL_LEVEL_LOGICAL)
122 
123 #ifdef WAL_DEBUG
124 extern PGDLLIMPORT bool XLOG_DEBUG;
125 #endif
126 
127 /*
128  * OR-able request flag bits for checkpoints. The "cause" bits are used only
129  * for logging purposes. Note: the flags must be defined so that it's
130  * sensible to OR together request flags arising from different requestors.
131  */
132 
133 /* These directly affect the behavior of CreateCheckPoint and subsidiaries */
134 #define CHECKPOINT_IS_SHUTDOWN 0x0001 /* Checkpoint is for shutdown */
135 #define CHECKPOINT_END_OF_RECOVERY 0x0002 /* Like shutdown checkpoint, but
136  * issued at end of WAL recovery */
137 #define CHECKPOINT_IMMEDIATE 0x0004 /* Do it without delays */
138 #define CHECKPOINT_FORCE 0x0008 /* Force even if no activity */
139 #define CHECKPOINT_FLUSH_ALL 0x0010 /* Flush all pages, including those
140  * belonging to unlogged tables */
141 /* These are important to RequestCheckpoint */
142 #define CHECKPOINT_WAIT 0x0020 /* Wait for completion */
143 #define CHECKPOINT_REQUESTED 0x0040 /* Checkpoint request has been made */
144 /* These indicate the cause of a checkpoint request */
145 #define CHECKPOINT_CAUSE_XLOG 0x0080 /* XLOG consumption */
146 #define CHECKPOINT_CAUSE_TIME 0x0100 /* Elapsed time */
147 
148 /*
149  * Flag bits for the record being inserted, set using XLogSetRecordFlags().
150  */
151 #define XLOG_INCLUDE_ORIGIN 0x01 /* include the replication origin */
152 #define XLOG_MARK_UNIMPORTANT 0x02 /* record not important for durability */
153 
154 
155 /* Checkpoint statistics */
156 typedef struct CheckpointStatsData
157 {
158  TimestampTz ckpt_start_t; /* start of checkpoint */
159  TimestampTz ckpt_write_t; /* start of flushing buffers */
160  TimestampTz ckpt_sync_t; /* start of fsyncs */
161  TimestampTz ckpt_sync_end_t; /* end of fsyncs */
162  TimestampTz ckpt_end_t; /* end of checkpoint */
163 
164  int ckpt_bufs_written; /* # of buffers written */
165 
166  int ckpt_segs_added; /* # of new xlog segments created */
167  int ckpt_segs_removed; /* # of xlog segments deleted */
168  int ckpt_segs_recycled; /* # of xlog segments recycled */
169 
170  int ckpt_sync_rels; /* # of relations synced */
171  uint64 ckpt_longest_sync; /* Longest sync for one relation */
172  uint64 ckpt_agg_sync_time; /* The sum of all the individual sync
173  * times, which is not necessarily the
174  * same as the total elapsed time for the
175  * entire sync phase. */
177 
179 
180 /*
181  * GetWALAvailability return codes
182  */
183 typedef enum WALAvailability
184 {
185  WALAVAIL_INVALID_LSN, /* parameter error */
186  WALAVAIL_RESERVED, /* WAL segment is within max_wal_size */
187  WALAVAIL_EXTENDED, /* WAL segment is reserved by a slot or
188  * wal_keep_size */
189  WALAVAIL_UNRESERVED, /* no longer reserved, but not removed yet */
190  WALAVAIL_REMOVED /* WAL segment has been removed */
192 
193 struct XLogRecData;
194 struct XLogReaderState;
195 
196 extern XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata,
197  XLogRecPtr fpw_lsn,
198  uint8 flags,
199  int num_fpi,
200  bool topxid_included);
201 extern void XLogFlush(XLogRecPtr record);
202 extern bool XLogBackgroundFlush(void);
203 extern bool XLogNeedsFlush(XLogRecPtr record);
204 extern int XLogFileInit(XLogSegNo logsegno, TimeLineID logtli);
205 extern int XLogFileOpen(XLogSegNo segno, TimeLineID tli);
206 
207 extern void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli);
209 extern void XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN);
211 
212 extern void xlog_redo(struct XLogReaderState *record);
213 extern void xlog_desc(StringInfo buf, struct XLogReaderState *record);
214 extern const char *xlog_identify(uint8 info);
215 
216 extern void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli);
217 
218 extern bool RecoveryInProgress(void);
219 extern RecoveryState GetRecoveryState(void);
220 extern bool XLogInsertAllowed(void);
221 extern XLogRecPtr GetXLogInsertRecPtr(void);
222 extern XLogRecPtr GetXLogWriteRecPtr(void);
223 
224 extern uint64 GetSystemIdentifier(void);
225 extern char *GetMockAuthenticationNonce(void);
226 extern bool DataChecksumsEnabled(void);
228 extern Size XLOGShmemSize(void);
229 extern void XLOGShmemInit(void);
230 extern void BootStrapXLOG(void);
231 extern void InitializeWalConsistencyChecking(void);
232 extern void LocalProcessControlFile(bool reset);
234 extern void StartupXLOG(void);
235 extern void ShutdownXLOG(int code, Datum arg);
236 extern void CreateCheckPoint(int flags);
237 extern bool CreateRestartPoint(int flags);
239 extern void XLogPutNextOid(Oid nextOid);
240 extern XLogRecPtr XLogRestorePoint(const char *rpName);
241 extern void UpdateFullPageWrites(void);
242 extern void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p);
243 extern XLogRecPtr GetRedoRecPtr(void);
244 extern XLogRecPtr GetInsertRecPtr(void);
245 extern XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI);
248 
249 extern void SetWalWriterSleeping(bool sleeping);
250 
251 /*
252  * Routines used by xlogrecovery.c to call back into xlog.c during recovery.
253  */
254 extern void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI);
255 extern bool XLogCheckpointNeeded(XLogSegNo new_segno);
258 extern void SetInstallXLogFileSegmentActive(void);
259 extern bool IsInstallXLogFileSegmentActive(void);
260 extern void XLogShutdownWalRcv(void);
261 
262 /*
263  * Routines to start, stop, and get status of a base backup.
264  */
265 
266 /*
267  * Session-level status of base backups
268  *
269  * This is used in parallel with the shared memory status to control parallel
270  * execution of base backup functions for a given session, be it a backend
271  * dedicated to replication or a normal backend connected to a database. The
272  * update of the session-level status happens at the same time as the shared
273  * memory counters to keep a consistent global and local state of the backups
274  * running.
275  */
276 typedef enum SessionBackupState
277 {
281 
282 extern void do_pg_backup_start(const char *backupidstr, bool fast,
283  List **tablespaces, BackupState *state,
284  StringInfo tblspcmapfile);
285 extern void do_pg_backup_stop(BackupState *state, bool waitforarchive);
286 extern void do_pg_abort_backup(int code, Datum arg);
289 
290 /* File path names (all relative to $PGDATA) */
291 #define RECOVERY_SIGNAL_FILE "recovery.signal"
292 #define STANDBY_SIGNAL_FILE "standby.signal"
293 #define BACKUP_LABEL_FILE "backup_label"
294 #define BACKUP_LABEL_OLD "backup_label.old"
295 
296 #define TABLESPACE_MAP "tablespace_map"
297 #define TABLESPACE_MAP_OLD "tablespace_map.old"
298 
299 /* files to signal promotion to primary */
300 #define PROMOTE_SIGNAL_FILE "promote"
301 
302 #endif /* XLOG_H */
#define PGDLLIMPORT
Definition: c.h:1326
unsigned char uint8
Definition: c.h:493
size_t Size
Definition: c.h:594
int64 TimestampTz
Definition: timestamp.h:39
void * arg
static char * buf
Definition: pg_test_fsync.c:67
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:170
uint64 ckpt_longest_sync
Definition: xlog.h:169
TimestampTz ckpt_start_t
Definition: xlog.h:156
TimestampTz ckpt_end_t
Definition: xlog.h:160
int ckpt_segs_removed
Definition: xlog.h:165
TimestampTz ckpt_write_t
Definition: xlog.h:157
int ckpt_segs_added
Definition: xlog.h:164
TimestampTz ckpt_sync_end_t
Definition: xlog.h:159
TimestampTz ckpt_sync_t
Definition: xlog.h:158
int ckpt_bufs_written
Definition: xlog.h:162
int ckpt_segs_recycled
Definition: xlog.h:166
int ckpt_sync_rels
Definition: xlog.h:168
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:3113
uint64 GetSystemIdentifier(void)
Definition: xlog.c:4203
void UpdateFullPageWrites(void)
Definition: xlog.c:7674
bool RecoveryInProgress(void)
Definition: xlog.c:5948
void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p)
Definition: xlog.c:6081
TimeLineID GetWALInsertionTimeLine(void)
Definition: xlog.c:6136
PGDLLIMPORT bool log_checkpoints
Definition: xlog.c:132
void do_pg_abort_backup(int code, Datum arg)
Definition: xlog.c:8882
XLogSegNo XLogGetLastRemovedSegno(void)
Definition: xlog.c:3491
void xlog_desc(StringInfo buf, struct XLogReaderState *record)
Definition: xlogdesc.c:37
XLogRecPtr GetRedoRecPtr(void)
Definition: xlog.c:6051
void SetInstallXLogFileSegmentActive(void)
Definition: xlog.c:8974
XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata, XLogRecPtr fpw_lsn, uint8 flags, int num_fpi, bool topxid_included)
Definition: xlog.c:731
void StartupXLOG(void)
Definition: xlog.c:5056
bool IsInstallXLogFileSegmentActive(void)
Definition: xlog.c:8982
PGDLLIMPORT XLogRecPtr XactLastRecEnd
Definition: xlog.c:257
ArchiveMode
Definition: xlog.h:59
@ ARCHIVE_MODE_ALWAYS
Definition: xlog.h:62
@ ARCHIVE_MODE_OFF
Definition: xlog.h:60
@ ARCHIVE_MODE_ON
Definition: xlog.h:61
bool CreateRestartPoint(int flags)
Definition: xlog.c:7119
PGDLLIMPORT bool EnableHotStandby
Definition: xlog.c:124
XLogRecPtr GetInsertRecPtr(void)
Definition: xlog.c:6096
SessionBackupState get_backup_status(void)
Definition: xlog.c:8589
void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3460
WALAvailability
Definition: xlog.h:182
@ WALAVAIL_REMOVED
Definition: xlog.h:188
@ WALAVAIL_RESERVED
Definition: xlog.h:184
@ WALAVAIL_UNRESERVED
Definition: xlog.h:187
@ WALAVAIL_EXTENDED
Definition: xlog.h:185
@ WALAVAIL_INVALID_LSN
Definition: xlog.h:183
PGDLLIMPORT CheckpointStatsData CheckpointStats
Definition: xlog.c:212
WALAvailability GetWALAvailability(XLogRecPtr targetLSN)
Definition: xlog.c:7391
PGDLLIMPORT int wal_retrieve_retry_interval
Definition: xlog.c:137
void XLOGShmemInit(void)
Definition: xlog.c:4560
void ShutdownXLOG(int code, Datum arg)
Definition: xlog.c:6199
bool DataChecksumsEnabled(void)
Definition: xlog.c:4223
RecoveryState GetRecoveryState(void)
Definition: xlog.c:5984
char * GetMockAuthenticationNonce(void)
Definition: xlog.c:4213
PGDLLIMPORT int wal_compression
Definition: xlog.c:127
void XLogSetReplicationSlotMinimumLSN(XLogRecPtr lsn)
Definition: xlog.c:2421
void SwitchIntoArchiveRecovery(XLogRecPtr EndRecPtr, TimeLineID replayTLI)
Definition: xlog.c:5823
WalCompression
Definition: xlog.h:76
@ WAL_COMPRESSION_NONE
Definition: xlog.h:77
@ WAL_COMPRESSION_LZ4
Definition: xlog.h:79
@ WAL_COMPRESSION_PGLZ
Definition: xlog.h:78
@ WAL_COMPRESSION_ZSTD
Definition: xlog.h:80
PGDLLIMPORT int wal_decode_buffer_size
Definition: xlog.c:139
XLogRecPtr GetXLogInsertRecPtr(void)
Definition: xlog.c:8923
Size XLOGShmemSize(void)
Definition: xlog.c:4510
void SetWalWriterSleeping(bool sleeping)
Definition: xlog.c:8997
struct CheckpointStatsData CheckpointStatsData
int XLogFileOpen(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3351
XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI)
Definition: xlog.c:6113
WalLevel GetActiveWalLevelOnStandby(void)
Definition: xlog.c:4501
PGDLLIMPORT int CheckPointSegments
Definition: xlog.c:159
void xlog_redo(struct XLogReaderState *record)
Definition: xlog.c:7743
void InitializeWalConsistencyChecking(void)
Definition: xlog.c:4426
PGDLLIMPORT bool fullPageWrites
Definition: xlog.c:125
void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI)
Definition: xlog.c:3635
XLogRecPtr GetLastImportantRecPtr(void)
Definition: xlog.c:6153
PGDLLIMPORT XLogRecPtr ProcLastRecPtr
Definition: xlog.c:256
PGDLLIMPORT char * wal_consistency_checking_string
Definition: xlog.c:128
SessionBackupState
Definition: xlog.h:275
@ SESSION_BACKUP_RUNNING
Definition: xlog.h:277
@ SESSION_BACKUP_NONE
Definition: xlog.h:276
bool XLogNeedsFlush(XLogRecPtr record)
Definition: xlog.c:2864
PGDLLIMPORT int wal_segment_size
Definition: xlog.c:146
void register_persistent_abort_backup_handler(void)
Definition: xlog.c:8909
void ReachedEndOfBackup(XLogRecPtr EndRecPtr, TimeLineID tli)
Definition: xlog.c:5861
void LocalProcessControlFile(bool reset)
Definition: xlog.c:4488
void BootStrapXLOG(void)
Definition: xlog.c:4669
PGDLLIMPORT int XLogArchiveMode
Definition: xlog.c:122
XLogRecPtr GetXLogWriteRecPtr(void)
Definition: xlog.c:8939
PGDLLIMPORT char * XLogArchiveCommand
Definition: xlog.c:123
PGDLLIMPORT int wal_keep_size_mb
Definition: xlog.c:119
bool XLogBackgroundFlush(void)
Definition: xlog.c:2725
PGDLLIMPORT bool * wal_consistency_checking
Definition: xlog.c:129
PGDLLIMPORT int max_slot_wal_keep_size_mb
Definition: xlog.c:138
bool XLogInsertAllowed(void)
Definition: xlog.c:6003
PGDLLIMPORT int sync_method
Definition: xlog.c:133
void do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces, BackupState *state, StringInfo tblspcmapfile)
Definition: xlog.c:8293
PGDLLIMPORT bool wal_init_zero
Definition: xlog.c:130
PGDLLIMPORT int min_wal_size_mb
Definition: xlog.c:118
XLogRecPtr XLogRestorePoint(const char *rpName)
Definition: xlog.c:7586
const char * xlog_identify(uint8 info)
Definition: xlogdesc.c:154
PGDLLIMPORT int XLOGbuffers
Definition: xlog.c:120
void do_pg_backup_stop(BackupState *state, bool waitforarchive)
Definition: xlog.c:8608
PGDLLIMPORT bool wal_recycle
Definition: xlog.c:131
WalLevel
Definition: xlog.h:68
@ WAL_LEVEL_REPLICA
Definition: xlog.h:70
@ WAL_LEVEL_LOGICAL
Definition: xlog.h:71
@ WAL_LEVEL_MINIMAL
Definition: xlog.h:69
XLogRecPtr GetFakeLSNForUnloggedRel(void)
Definition: xlog.c:4239
PGDLLIMPORT int XLogArchiveTimeout
Definition: xlog.c:121
void XLogPutNextOid(Oid nextOid)
Definition: xlog.c:7531
void XLogFlush(XLogRecPtr record)
Definition: xlog.c:2535
PGDLLIMPORT XLogRecPtr XactLastCommitEnd
Definition: xlog.c:258
PGDLLIMPORT int wal_level
Definition: xlog.c:134
PGDLLIMPORT bool wal_log_hints
Definition: xlog.c:126
RecoveryState
Definition: xlog.h:85
@ RECOVERY_STATE_CRASH
Definition: xlog.h:86
@ RECOVERY_STATE_DONE
Definition: xlog.h:88
@ RECOVERY_STATE_ARCHIVE
Definition: xlog.h:87
void XLogShutdownWalRcv(void)
Definition: xlog.c:8963
void CreateCheckPoint(int flags)
Definition: xlog.c:6476
void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:8186
PGDLLIMPORT int max_wal_size_mb
Definition: xlog.c:117
void XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN)
Definition: xlog.c:2380
PGDLLIMPORT bool track_wal_io_timing
Definition: xlog.c:140
bool XLogCheckpointNeeded(XLogSegNo new_segno)
Definition: xlog.c:2065
uint64 XLogRecPtr
Definition: xlogdefs.h:21
uint32 TimeLineID
Definition: xlogdefs.h:59
uint64 XLogSegNo
Definition: xlogdefs.h:48