PostgreSQL Source Code  git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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;
55 extern PGDLLIMPORT int CommitDelay;
56 extern PGDLLIMPORT int CommitSiblings;
59 
61 
62 /* Archive modes */
63 typedef enum ArchiveMode
64 {
65  ARCHIVE_MODE_OFF = 0, /* disabled */
66  ARCHIVE_MODE_ON, /* enabled while server is running normally */
67  ARCHIVE_MODE_ALWAYS, /* enabled always (even during recovery) */
69 extern PGDLLIMPORT int XLogArchiveMode;
70 
71 /* WAL levels */
72 typedef enum WalLevel
73 {
78 
79 /* Compression algorithms for WAL */
80 typedef enum WalCompression
81 {
87 
88 /* Recovery states */
89 typedef enum RecoveryState
90 {
91  RECOVERY_STATE_CRASH = 0, /* crash recovery */
92  RECOVERY_STATE_ARCHIVE, /* archive recovery */
93  RECOVERY_STATE_DONE, /* currently in production */
95 
96 extern PGDLLIMPORT int wal_level;
97 
98 /* Is WAL archiving enabled (always or only while server is running normally)? */
99 #define XLogArchivingActive() \
100  (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode > ARCHIVE_MODE_OFF)
101 /* Is WAL archiving enabled always (even during recovery)? */
102 #define XLogArchivingAlways() \
103  (AssertMacro(XLogArchiveMode == ARCHIVE_MODE_OFF || wal_level >= WAL_LEVEL_REPLICA), XLogArchiveMode == ARCHIVE_MODE_ALWAYS)
104 
105 /*
106  * Is WAL-logging necessary for archival or log-shipping, or can we skip
107  * WAL-logging if we fsync() the data before committing instead?
108  */
109 #define XLogIsNeeded() (wal_level >= WAL_LEVEL_REPLICA)
110 
111 /*
112  * Is a full-page image needed for hint bit updates?
113  *
114  * Normally, we don't WAL-log hint bit updates, but if checksums are enabled,
115  * we have to protect them against torn page writes. When you only set
116  * individual bits on a page, it's still consistent no matter what combination
117  * of the bits make it to disk, but the checksum wouldn't match. Also WAL-log
118  * them if forced by wal_log_hints=on.
119  */
120 #define XLogHintBitIsNeeded() (DataChecksumsEnabled() || wal_log_hints)
121 
122 /* Do we need to WAL-log information required only for Hot Standby and logical replication? */
123 #define XLogStandbyInfoActive() (wal_level >= WAL_LEVEL_REPLICA)
124 
125 /* Do we need to WAL-log information required only for logical replication? */
126 #define XLogLogicalInfoActive() (wal_level >= WAL_LEVEL_LOGICAL)
127 
128 #ifdef WAL_DEBUG
129 extern PGDLLIMPORT bool XLOG_DEBUG;
130 #endif
131 
132 /*
133  * OR-able request flag bits for checkpoints. The "cause" bits are used only
134  * for logging purposes. Note: the flags must be defined so that it's
135  * sensible to OR together request flags arising from different requestors.
136  */
137 
138 /* These directly affect the behavior of CreateCheckPoint and subsidiaries */
139 #define CHECKPOINT_IS_SHUTDOWN 0x0001 /* Checkpoint is for shutdown */
140 #define CHECKPOINT_END_OF_RECOVERY 0x0002 /* Like shutdown checkpoint, but
141  * issued at end of WAL recovery */
142 #define CHECKPOINT_IMMEDIATE 0x0004 /* Do it without delays */
143 #define CHECKPOINT_FORCE 0x0008 /* Force even if no activity */
144 #define CHECKPOINT_FLUSH_ALL 0x0010 /* Flush all pages, including those
145  * belonging to unlogged tables */
146 /* These are important to RequestCheckpoint */
147 #define CHECKPOINT_WAIT 0x0020 /* Wait for completion */
148 #define CHECKPOINT_REQUESTED 0x0040 /* Checkpoint request has been made */
149 /* These indicate the cause of a checkpoint request */
150 #define CHECKPOINT_CAUSE_XLOG 0x0080 /* XLOG consumption */
151 #define CHECKPOINT_CAUSE_TIME 0x0100 /* Elapsed time */
152 
153 /*
154  * Flag bits for the record being inserted, set using XLogSetRecordFlags().
155  */
156 #define XLOG_INCLUDE_ORIGIN 0x01 /* include the replication origin */
157 #define XLOG_MARK_UNIMPORTANT 0x02 /* record not important for durability */
158 
159 
160 /* Checkpoint statistics */
161 typedef struct CheckpointStatsData
162 {
163  TimestampTz ckpt_start_t; /* start of checkpoint */
164  TimestampTz ckpt_write_t; /* start of flushing buffers */
165  TimestampTz ckpt_sync_t; /* start of fsyncs */
166  TimestampTz ckpt_sync_end_t; /* end of fsyncs */
167  TimestampTz ckpt_end_t; /* end of checkpoint */
168 
169  int ckpt_bufs_written; /* # of buffers written */
170  int ckpt_slru_written; /* # of SLRU buffers written */
171 
172  int ckpt_segs_added; /* # of new xlog segments created */
173  int ckpt_segs_removed; /* # of xlog segments deleted */
174  int ckpt_segs_recycled; /* # of xlog segments recycled */
175 
176  int ckpt_sync_rels; /* # of relations synced */
177  uint64 ckpt_longest_sync; /* Longest sync for one relation */
178  uint64 ckpt_agg_sync_time; /* The sum of all the individual sync
179  * times, which is not necessarily the
180  * same as the total elapsed time for the
181  * entire sync phase. */
183 
185 
186 /*
187  * GetWALAvailability return codes
188  */
189 typedef enum WALAvailability
190 {
191  WALAVAIL_INVALID_LSN, /* parameter error */
192  WALAVAIL_RESERVED, /* WAL segment is within max_wal_size */
193  WALAVAIL_EXTENDED, /* WAL segment is reserved by a slot or
194  * wal_keep_size */
195  WALAVAIL_UNRESERVED, /* no longer reserved, but not removed yet */
196  WALAVAIL_REMOVED, /* WAL segment has been removed */
198 
199 struct XLogRecData;
200 struct XLogReaderState;
201 
202 extern XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata,
203  XLogRecPtr fpw_lsn,
204  uint8 flags,
205  int num_fpi,
206  bool topxid_included);
207 extern void XLogFlush(XLogRecPtr record);
208 extern bool XLogBackgroundFlush(void);
209 extern bool XLogNeedsFlush(XLogRecPtr record);
210 extern int XLogFileInit(XLogSegNo logsegno, TimeLineID logtli);
211 extern int XLogFileOpen(XLogSegNo segno, TimeLineID tli);
212 
213 extern void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli);
216 extern void XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN);
218 
219 extern void xlog_redo(struct XLogReaderState *record);
220 extern void xlog_desc(StringInfo buf, struct XLogReaderState *record);
221 extern const char *xlog_identify(uint8 info);
222 
223 extern void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli);
224 
225 extern bool RecoveryInProgress(void);
226 extern RecoveryState GetRecoveryState(void);
227 extern bool XLogInsertAllowed(void);
228 extern XLogRecPtr GetXLogInsertRecPtr(void);
229 extern XLogRecPtr GetXLogWriteRecPtr(void);
230 
231 extern uint64 GetSystemIdentifier(void);
232 extern char *GetMockAuthenticationNonce(void);
233 extern bool DataChecksumsEnabled(void);
235 extern Size XLOGShmemSize(void);
236 extern void XLOGShmemInit(void);
237 extern void BootStrapXLOG(uint32 data_checksum_version);
238 extern void InitializeWalConsistencyChecking(void);
239 extern void LocalProcessControlFile(bool reset);
241 extern void StartupXLOG(void);
242 extern void ShutdownXLOG(int code, Datum arg);
243 extern bool CreateCheckPoint(int flags);
244 extern bool CreateRestartPoint(int flags);
246 extern void XLogPutNextOid(Oid nextOid);
247 extern XLogRecPtr XLogRestorePoint(const char *rpName);
248 extern void UpdateFullPageWrites(void);
249 extern void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p);
250 extern XLogRecPtr GetRedoRecPtr(void);
251 extern XLogRecPtr GetInsertRecPtr(void);
252 extern XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI);
256 
257 extern void SetWalWriterSleeping(bool sleeping);
258 
259 extern Size WALReadFromBuffers(char *dstbuf, XLogRecPtr startptr, Size count,
260  TimeLineID tli);
261 
262 /*
263  * Routines used by xlogrecovery.c to call back into xlog.c during recovery.
264  */
265 extern void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI);
266 extern bool XLogCheckpointNeeded(XLogSegNo new_segno);
269 extern void SetInstallXLogFileSegmentActive(void);
270 extern bool IsInstallXLogFileSegmentActive(void);
271 extern void XLogShutdownWalRcv(void);
272 
273 /*
274  * Routines to start, stop, and get status of a base backup.
275  */
276 
277 /*
278  * Session-level status of base backups
279  *
280  * This is used in parallel with the shared memory status to control parallel
281  * execution of base backup functions for a given session, be it a backend
282  * dedicated to replication or a normal backend connected to a database. The
283  * update of the session-level status happens at the same time as the shared
284  * memory counters to keep a consistent global and local state of the backups
285  * running.
286  */
287 typedef enum SessionBackupState
288 {
292 
293 extern void do_pg_backup_start(const char *backupidstr, bool fast,
294  List **tablespaces, BackupState *state,
295  StringInfo tblspcmapfile);
296 extern void do_pg_backup_stop(BackupState *state, bool waitforarchive);
297 extern void do_pg_abort_backup(int code, Datum arg);
300 
301 /* File path names (all relative to $PGDATA) */
302 #define RECOVERY_SIGNAL_FILE "recovery.signal"
303 #define STANDBY_SIGNAL_FILE "standby.signal"
304 #define BACKUP_LABEL_FILE "backup_label"
305 #define BACKUP_LABEL_OLD "backup_label.old"
306 
307 #define TABLESPACE_MAP "tablespace_map"
308 #define TABLESPACE_MAP_OLD "tablespace_map.old"
309 
310 /* files to signal promotion to primary */
311 #define PROMOTE_SIGNAL_FILE "promote"
312 
313 #endif /* XLOG_H */
unsigned int uint32
Definition: c.h:518
#define PGDLLIMPORT
Definition: c.h:1321
unsigned char uint8
Definition: c.h:516
size_t Size
Definition: c.h:610
int64 TimestampTz
Definition: timestamp.h:39
void * arg
static char * buf
Definition: pg_test_fsync.c:72
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:176
uint64 ckpt_longest_sync
Definition: xlog.h:175
TimestampTz ckpt_start_t
Definition: xlog.h:161
TimestampTz ckpt_end_t
Definition: xlog.h:165
int ckpt_segs_removed
Definition: xlog.h:171
TimestampTz ckpt_write_t
Definition: xlog.h:162
int ckpt_segs_added
Definition: xlog.h:170
TimestampTz ckpt_sync_end_t
Definition: xlog.h:164
TimestampTz ckpt_sync_t
Definition: xlog.h:163
int ckpt_bufs_written
Definition: xlog.h:167
int ckpt_segs_recycled
Definition: xlog.h:172
int ckpt_slru_written
Definition: xlog.h:168
int ckpt_sync_rels
Definition: xlog.h:174
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:3380
uint64 GetSystemIdentifier(void)
Definition: xlog.c:4568
void UpdateFullPageWrites(void)
Definition: xlog.c:8166
bool RecoveryInProgress(void)
Definition: xlog.c:6334
void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p)
Definition: xlog.c:6467
TimeLineID GetWALInsertionTimeLine(void)
Definition: xlog.c:6520
PGDLLIMPORT bool log_checkpoints
Definition: xlog.c:129
void do_pg_abort_backup(int code, Datum arg)
Definition: xlog.c:9394
XLogSegNo XLogGetLastRemovedSegno(void)
Definition: xlog.c:3758
void xlog_desc(StringInfo buf, struct XLogReaderState *record)
Definition: xlogdesc.c:58
Size WALReadFromBuffers(char *dstbuf, XLogRecPtr startptr, Size count, TimeLineID tli)
Definition: xlog.c:1748
XLogRecPtr GetRedoRecPtr(void)
Definition: xlog.c:6437
void SetInstallXLogFileSegmentActive(void)
Definition: xlog.c:9484
XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata, XLogRecPtr fpw_lsn, uint8 flags, int num_fpi, bool topxid_included)
Definition: xlog.c:748
void StartupXLOG(void)
Definition: xlog.c:5429
bool IsInstallXLogFileSegmentActive(void)
Definition: xlog.c:9492
PGDLLIMPORT XLogRecPtr XactLastRecEnd
Definition: xlog.c:254
void BootStrapXLOG(uint32 data_checksum_version)
Definition: xlog.c:5033
ArchiveMode
Definition: xlog.h:64
@ ARCHIVE_MODE_ALWAYS
Definition: xlog.h:67
@ ARCHIVE_MODE_OFF
Definition: xlog.h:65
@ ARCHIVE_MODE_ON
Definition: xlog.h:66
bool CreateRestartPoint(int flags)
Definition: xlog.c:7591
PGDLLIMPORT int wal_sync_method
Definition: xlog.c:130
PGDLLIMPORT bool EnableHotStandby
Definition: xlog.c:121
XLogRecPtr GetInsertRecPtr(void)
Definition: xlog.c:6482
SessionBackupState get_backup_status(void)
Definition: xlog.c:9101
void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3727
WALAvailability
Definition: xlog.h:188
@ WALAVAIL_REMOVED
Definition: xlog.h:194
@ WALAVAIL_RESERVED
Definition: xlog.h:190
@ WALAVAIL_UNRESERVED
Definition: xlog.h:193
@ WALAVAIL_EXTENDED
Definition: xlog.h:191
@ WALAVAIL_INVALID_LSN
Definition: xlog.h:189
PGDLLIMPORT CheckpointStatsData CheckpointStats
Definition: xlog.c:209
WALAvailability GetWALAvailability(XLogRecPtr targetLSN)
Definition: xlog.c:7869
PGDLLIMPORT int wal_retrieve_retry_interval
Definition: xlog.c:134
void XLOGShmemInit(void)
Definition: xlog.c:4918
void ShutdownXLOG(int code, Datum arg)
Definition: xlog.c:6602
bool DataChecksumsEnabled(void)
Definition: xlog.c:4588
RecoveryState GetRecoveryState(void)
Definition: xlog.c:6370
char * GetMockAuthenticationNonce(void)
Definition: xlog.c:4578
PGDLLIMPORT int wal_compression
Definition: xlog.c:124
void XLogSetReplicationSlotMinimumLSN(XLogRecPtr lsn)
Definition: xlog.c:2688
PGDLLIMPORT int CommitSiblings
Definition: xlog.c:133
void SwitchIntoArchiveRecovery(XLogRecPtr EndRecPtr, TimeLineID replayTLI)
Definition: xlog.c:6209
WalCompression
Definition: xlog.h:81
@ WAL_COMPRESSION_NONE
Definition: xlog.h:82
@ WAL_COMPRESSION_LZ4
Definition: xlog.h:84
@ WAL_COMPRESSION_PGLZ
Definition: xlog.h:83
@ WAL_COMPRESSION_ZSTD
Definition: xlog.h:85
PGDLLIMPORT int wal_decode_buffer_size
Definition: xlog.c:136
XLogRecPtr GetXLogInsertRecPtr(void)
Definition: xlog.c:9435
Size XLOGShmemSize(void)
Definition: xlog.c:4868
void SetWalWriterSleeping(bool sleeping)
Definition: xlog.c:9507
struct CheckpointStatsData CheckpointStatsData
int XLogFileOpen(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3618
XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI)
Definition: xlog.c:6499
WalLevel GetActiveWalLevelOnStandby(void)
Definition: xlog.c:4859
PGDLLIMPORT int CheckPointSegments
Definition: xlog.c:156
void xlog_redo(struct XLogReaderState *record)
Definition: xlog.c:8235
void InitializeWalConsistencyChecking(void)
Definition: xlog.c:4784
PGDLLIMPORT bool fullPageWrites
Definition: xlog.c:122
void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI)
Definition: xlog.c:3940
XLogRecPtr GetLastImportantRecPtr(void)
Definition: xlog.c:6556
PGDLLIMPORT XLogRecPtr ProcLastRecPtr
Definition: xlog.c:253
PGDLLIMPORT char * wal_consistency_checking_string
Definition: xlog.c:125
SessionBackupState
Definition: xlog.h:286
@ SESSION_BACKUP_RUNNING
Definition: xlog.h:288
@ SESSION_BACKUP_NONE
Definition: xlog.h:287
bool XLogNeedsFlush(XLogRecPtr record)
Definition: xlog.c:3133
PGDLLIMPORT int wal_segment_size
Definition: xlog.c:143
void register_persistent_abort_backup_handler(void)
Definition: xlog.c:9421
void ReachedEndOfBackup(XLogRecPtr EndRecPtr, TimeLineID tli)
Definition: xlog.c:6247
void LocalProcessControlFile(bool reset)
Definition: xlog.c:4846
XLogSegNo XLogGetOldestSegno(TimeLineID tli)
Definition: xlog.c:3774
PGDLLIMPORT int XLogArchiveMode
Definition: xlog.c:119
XLogRecPtr GetXLogWriteRecPtr(void)
Definition: xlog.c:9451
PGDLLIMPORT char * XLogArchiveCommand
Definition: xlog.c:120
PGDLLIMPORT int wal_keep_size_mb
Definition: xlog.c:116
bool XLogBackgroundFlush(void)
Definition: xlog.c:2990
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:6389
void do_pg_backup_start(const char *backupidstr, bool fast, List **tablespaces, BackupState *state, StringInfo tblspcmapfile)
Definition: xlog.c:8792
PGDLLIMPORT bool wal_init_zero
Definition: xlog.c:127
PGDLLIMPORT int min_wal_size_mb
Definition: xlog.c:115
PGDLLIMPORT int CommitDelay
Definition: xlog.c:132
XLogRecPtr XLogRestorePoint(const char *rpName)
Definition: xlog.c:8078
const char * xlog_identify(uint8 info)
Definition: xlogdesc.c:173
PGDLLIMPORT int XLOGbuffers
Definition: xlog.c:117
TimeLineID GetWALInsertionTimeLineIfSet(void)
Definition: xlog.c:6536
void do_pg_backup_stop(BackupState *state, bool waitforarchive)
Definition: xlog.c:9120
PGDLLIMPORT bool wal_recycle
Definition: xlog.c:128
WalLevel
Definition: xlog.h:73
@ WAL_LEVEL_REPLICA
Definition: xlog.h:75
@ WAL_LEVEL_LOGICAL
Definition: xlog.h:76
@ WAL_LEVEL_MINIMAL
Definition: xlog.h:74
bool CreateCheckPoint(int flags)
Definition: xlog.c:6889
XLogRecPtr GetFakeLSNForUnloggedRel(void)
Definition: xlog.c:4604
PGDLLIMPORT int XLogArchiveTimeout
Definition: xlog.c:118
void XLogPutNextOid(Oid nextOid)
Definition: xlog.c:8023
void XLogFlush(XLogRecPtr record)
Definition: xlog.c:2802
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:90
@ RECOVERY_STATE_CRASH
Definition: xlog.h:91
@ RECOVERY_STATE_DONE
Definition: xlog.h:93
@ RECOVERY_STATE_ARCHIVE
Definition: xlog.h:92
void XLogShutdownWalRcv(void)
Definition: xlog.c:9473
void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:8683
PGDLLIMPORT int max_wal_size_mb
Definition: xlog.c:114
void XLogSetAsyncXactLSN(XLogRecPtr asyncXactLSN)
Definition: xlog.c:2631
PGDLLIMPORT bool track_wal_io_timing
Definition: xlog.c:137
bool XLogCheckpointNeeded(XLogSegNo new_segno)
Definition: xlog.c:2290
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