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-2022, 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/xlogdefs.h"
15 #include "access/xlogreader.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 
195 extern XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata,
196  XLogRecPtr fpw_lsn,
197  uint8 flags,
198  int num_fpi,
199  bool topxid_included);
200 extern void XLogFlush(XLogRecPtr RecPtr);
201 extern bool XLogBackgroundFlush(void);
202 extern bool XLogNeedsFlush(XLogRecPtr RecPtr);
203 extern int XLogFileInit(XLogSegNo segno, TimeLineID tli);
204 extern int XLogFileOpen(XLogSegNo segno, TimeLineID tli);
205 
206 extern void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli);
208 extern void XLogSetAsyncXactLSN(XLogRecPtr record);
210 
211 extern void xlog_redo(XLogReaderState *record);
212 extern void xlog_desc(StringInfo buf, XLogReaderState *record);
213 extern const char *xlog_identify(uint8 info);
214 
215 extern void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli);
216 
217 extern bool RecoveryInProgress(void);
218 extern RecoveryState GetRecoveryState(void);
219 extern bool XLogInsertAllowed(void);
220 extern XLogRecPtr GetXLogInsertRecPtr(void);
221 extern XLogRecPtr GetXLogWriteRecPtr(void);
222 
223 extern uint64 GetSystemIdentifier(void);
224 extern char *GetMockAuthenticationNonce(void);
225 extern bool DataChecksumsEnabled(void);
227 extern Size XLOGShmemSize(void);
228 extern void XLOGShmemInit(void);
229 extern void BootStrapXLOG(void);
230 extern void LocalProcessControlFile(bool reset);
231 extern void StartupXLOG(void);
232 extern void ShutdownXLOG(int code, Datum arg);
233 extern void CreateCheckPoint(int flags);
234 extern bool CreateRestartPoint(int flags);
236 extern void XLogPutNextOid(Oid nextOid);
237 extern XLogRecPtr XLogRestorePoint(const char *rpName);
238 extern void UpdateFullPageWrites(void);
239 extern void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p);
240 extern XLogRecPtr GetRedoRecPtr(void);
241 extern XLogRecPtr GetInsertRecPtr(void);
242 extern XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI);
245 
246 extern void SetWalWriterSleeping(bool sleeping);
247 
248 extern void assign_max_wal_size(int newval, void *extra);
249 extern void assign_checkpoint_completion_target(double newval, void *extra);
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);
256 extern void SwitchIntoArchiveRecovery(XLogRecPtr EndRecPtr, TimeLineID replayTLI);
257 extern void ReachedEndOfBackup(XLogRecPtr EndRecPtr, TimeLineID tli);
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 XLogRecPtr do_pg_backup_start(const char *backupidstr, bool fast,
283  TimeLineID *starttli_p, StringInfo labelfile,
284  List **tablespaces, StringInfo tblspcmapfile);
285 extern XLogRecPtr do_pg_backup_stop(char *labelfile, bool waitforarchive,
286  TimeLineID *stoptli_p);
287 extern void do_pg_abort_backup(int code, Datum arg);
290 
291 /* File path names (all relative to $PGDATA) */
292 #define RECOVERY_SIGNAL_FILE "recovery.signal"
293 #define STANDBY_SIGNAL_FILE "standby.signal"
294 #define BACKUP_LABEL_FILE "backup_label"
295 #define BACKUP_LABEL_OLD "backup_label.old"
296 
297 #define TABLESPACE_MAP "tablespace_map"
298 #define TABLESPACE_MAP_OLD "tablespace_map.old"
299 
300 /* files to signal promotion to primary */
301 #define PROMOTE_SIGNAL_FILE "promote"
302 
303 #endif /* XLOG_H */
#define PGDLLIMPORT
Definition: c.h:1331
unsigned char uint8
Definition: c.h:439
size_t Size
Definition: c.h:540
int64 TimestampTz
Definition: timestamp.h:39
#define newval
void * arg
static char * buf
Definition: pg_test_fsync.c:67
uintptr_t Datum
Definition: postgres.h:411
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:51
uint64 GetSystemIdentifier(void)
Definition: xlog.c:4206
XLogRecPtr do_pg_backup_start(const char *backupidstr, bool fast, TimeLineID *starttli_p, StringInfo labelfile, List **tablespaces, StringInfo tblspcmapfile)
Definition: xlog.c:8086
void UpdateFullPageWrites(void)
Definition: xlog.c:7472
bool RecoveryInProgress(void)
Definition: xlog.c:5762
void GetFullPageWriteInfo(XLogRecPtr *RedoRecPtr_p, bool *doPageWrites_p)
Definition: xlog.c:5895
TimeLineID GetWALInsertionTimeLine(void)
Definition: xlog.c:5950
PGDLLIMPORT bool log_checkpoints
Definition: xlog.c:130
void do_pg_abort_backup(int code, Datum arg)
Definition: xlog.c:8768
XLogSegNo XLogGetLastRemovedSegno(void)
Definition: xlog.c:3485
void xlog_desc(StringInfo buf, XLogReaderState *record)
Definition: xlogdesc.c:37
XLogRecPtr GetRedoRecPtr(void)
Definition: xlog.c:5865
void SetInstallXLogFileSegmentActive(void)
Definition: xlog.c:8863
bool XLogNeedsFlush(XLogRecPtr RecPtr)
Definition: xlog.c:2838
void XLogFlush(XLogRecPtr RecPtr)
Definition: xlog.c:2509
XLogRecPtr XLogInsertRecord(struct XLogRecData *rdata, XLogRecPtr fpw_lsn, uint8 flags, int num_fpi, bool topxid_included)
Definition: xlog.c:728
void StartupXLOG(void)
Definition: xlog.c:4886
bool IsInstallXLogFileSegmentActive(void)
Definition: xlog.c:8871
PGDLLIMPORT XLogRecPtr XactLastRecEnd
Definition: xlog.c:251
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:6920
PGDLLIMPORT bool EnableHotStandby
Definition: xlog.c:122
XLogRecPtr GetInsertRecPtr(void)
Definition: xlog.c:5910
SessionBackupState get_backup_status(void)
Definition: xlog.c:8428
void CheckXLogRemoved(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3454
void assign_checkpoint_completion_target(double newval, void *extra)
Definition: xlog.c:1978
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:206
WALAvailability GetWALAvailability(XLogRecPtr targetLSN)
Definition: xlog.c:7189
PGDLLIMPORT int wal_retrieve_retry_interval
Definition: xlog.c:135
void XLOGShmemInit(void)
Definition: xlog.c:4387
void ShutdownXLOG(int code, Datum arg)
Definition: xlog.c:6013
bool DataChecksumsEnabled(void)
Definition: xlog.c:4226
RecoveryState GetRecoveryState(void)
Definition: xlog.c:5798
int XLogFileInit(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3106
char * GetMockAuthenticationNonce(void)
Definition: xlog.c:4216
PGDLLIMPORT int wal_compression
Definition: xlog.c:125
void XLogSetReplicationSlotMinimumLSN(XLogRecPtr lsn)
Definition: xlog.c:2395
void SwitchIntoArchiveRecovery(XLogRecPtr EndRecPtr, TimeLineID replayTLI)
Definition: xlog.c:5637
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:137
XLogRecPtr GetXLogInsertRecPtr(void)
Definition: xlog.c:8812
Size XLOGShmemSize(void)
Definition: xlog.c:4337
void SetWalWriterSleeping(bool sleeping)
Definition: xlog.c:8886
struct CheckpointStatsData CheckpointStatsData
int XLogFileOpen(XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:3346
XLogRecPtr GetFlushRecPtr(TimeLineID *insertTLI)
Definition: xlog.c:5927
void XLogSetAsyncXactLSN(XLogRecPtr record)
Definition: xlog.c:2354
PGDLLIMPORT int CheckPointSegments
Definition: xlog.c:157
void assign_max_wal_size(int newval, void *extra)
Definition: xlog.c:1971
PGDLLIMPORT bool fullPageWrites
Definition: xlog.c:123
void RemoveNonParentXlogFiles(XLogRecPtr switchpoint, TimeLineID newTLI)
Definition: xlog.c:3630
XLogRecPtr GetLastImportantRecPtr(void)
Definition: xlog.c:5967
void xlog_redo(XLogReaderState *record)
Definition: xlog.c:7541
PGDLLIMPORT XLogRecPtr ProcLastRecPtr
Definition: xlog.c:250
PGDLLIMPORT char * wal_consistency_checking_string
Definition: xlog.c:126
SessionBackupState
Definition: xlog.h:275
@ SESSION_BACKUP_RUNNING
Definition: xlog.h:277
@ SESSION_BACKUP_NONE
Definition: xlog.h:276
PGDLLIMPORT int wal_segment_size
Definition: xlog.c:144
void register_persistent_abort_backup_handler(void)
Definition: xlog.c:8798
void ReachedEndOfBackup(XLogRecPtr EndRecPtr, TimeLineID tli)
Definition: xlog.c:5675
void LocalProcessControlFile(bool reset)
Definition: xlog.c:4326
void BootStrapXLOG(void)
Definition: xlog.c:4496
PGDLLIMPORT int XLogArchiveMode
Definition: xlog.c:120
XLogRecPtr GetXLogWriteRecPtr(void)
Definition: xlog.c:8828
PGDLLIMPORT char * XLogArchiveCommand
Definition: xlog.c:121
PGDLLIMPORT int wal_keep_size_mb
Definition: xlog.c:117
bool XLogBackgroundFlush(void)
Definition: xlog.c:2699
PGDLLIMPORT bool * wal_consistency_checking
Definition: xlog.c:127
PGDLLIMPORT int max_slot_wal_keep_size_mb
Definition: xlog.c:136
bool XLogInsertAllowed(void)
Definition: xlog.c:5817
PGDLLIMPORT int sync_method
Definition: xlog.c:131
PGDLLIMPORT bool wal_init_zero
Definition: xlog.c:128
PGDLLIMPORT int min_wal_size_mb
Definition: xlog.c:116
XLogRecPtr XLogRestorePoint(const char *rpName)
Definition: xlog.c:7384
const char * xlog_identify(uint8 info)
Definition: xlogdesc.c:154
PGDLLIMPORT int XLOGbuffers
Definition: xlog.c:118
PGDLLIMPORT bool wal_recycle
Definition: xlog.c:129
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:4242
PGDLLIMPORT int XLogArchiveTimeout
Definition: xlog.c:119
void XLogPutNextOid(Oid nextOid)
Definition: xlog.c:7329
PGDLLIMPORT XLogRecPtr XactLastCommitEnd
Definition: xlog.c:252
XLogRecPtr do_pg_backup_stop(char *labelfile, bool waitforarchive, TimeLineID *stoptli_p)
Definition: xlog.c:8446
PGDLLIMPORT int wal_level
Definition: xlog.c:132
PGDLLIMPORT bool wal_log_hints
Definition: xlog.c:124
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:8852
void CreateCheckPoint(int flags)
Definition: xlog.c:6279
void issue_xlog_fsync(int fd, XLogSegNo segno, TimeLineID tli)
Definition: xlog.c:7977
PGDLLIMPORT int max_wal_size_mb
Definition: xlog.c:115
PGDLLIMPORT bool track_wal_io_timing
Definition: xlog.c:138
bool XLogCheckpointNeeded(XLogSegNo new_segno)
Definition: xlog.c:2039
uint64 XLogRecPtr
Definition: xlogdefs.h:21
uint32 TimeLineID
Definition: xlogdefs.h:59
uint64 XLogSegNo
Definition: xlogdefs.h:48