PostgreSQL Source Code  git master
pg_control.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * pg_control.h
4  * The system control file "pg_control" is not a heap relation.
5  * However, we define it here so that the format is documented.
6  *
7  *
8  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
9  * Portions Copyright (c) 1994, Regents of the University of California
10  *
11  * src/include/catalog/pg_control.h
12  *
13  *-------------------------------------------------------------------------
14  */
15 #ifndef PG_CONTROL_H
16 #define PG_CONTROL_H
17 
18 #include "access/transam.h"
19 #include "access/xlogdefs.h"
20 #include "pgtime.h" /* for pg_time_t */
21 #include "port/pg_crc32c.h"
22 
23 
24 /* Version identifier for this pg_control format */
25 #define PG_CONTROL_VERSION 1700
26 
27 /* Nonce key length, see below */
28 #define MOCK_AUTH_NONCE_LEN 32
29 
30 /*
31  * Body of CheckPoint XLOG records. This is declared here because we keep
32  * a copy of the latest one in pg_control for possible disaster recovery.
33  * Changing this struct requires a PG_CONTROL_VERSION bump.
34  */
35 typedef struct CheckPoint
36 {
37  XLogRecPtr redo; /* next RecPtr available when we began to
38  * create CheckPoint (i.e. REDO start point) */
39  TimeLineID ThisTimeLineID; /* current TLI */
40  TimeLineID PrevTimeLineID; /* previous TLI, if this record begins a new
41  * timeline (equals ThisTimeLineID otherwise) */
42  bool fullPageWrites; /* current full_page_writes */
43  int wal_level; /* current wal_level */
44  FullTransactionId nextXid; /* next free transaction ID */
45  Oid nextOid; /* next free OID */
46  MultiXactId nextMulti; /* next free MultiXactId */
47  MultiXactOffset nextMultiOffset; /* next free MultiXact offset */
48  TransactionId oldestXid; /* cluster-wide minimum datfrozenxid */
49  Oid oldestXidDB; /* database with minimum datfrozenxid */
50  MultiXactId oldestMulti; /* cluster-wide minimum datminmxid */
51  Oid oldestMultiDB; /* database with minimum datminmxid */
52  pg_time_t time; /* time stamp of checkpoint */
53  TransactionId oldestCommitTsXid; /* oldest Xid with valid commit
54  * timestamp */
55  TransactionId newestCommitTsXid; /* newest Xid with valid commit
56  * timestamp */
57 
58  /*
59  * Oldest XID still running. This is only needed to initialize hot standby
60  * mode from an online checkpoint, so we only bother calculating this for
61  * online checkpoints and only when wal_level is replica. Otherwise it's
62  * set to InvalidTransactionId.
63  */
66 
67 /* XLOG info values for XLOG rmgr */
68 #define XLOG_CHECKPOINT_SHUTDOWN 0x00
69 #define XLOG_CHECKPOINT_ONLINE 0x10
70 #define XLOG_NOOP 0x20
71 #define XLOG_NEXTOID 0x30
72 #define XLOG_SWITCH 0x40
73 #define XLOG_BACKUP_END 0x50
74 #define XLOG_PARAMETER_CHANGE 0x60
75 #define XLOG_RESTORE_POINT 0x70
76 #define XLOG_FPW_CHANGE 0x80
77 #define XLOG_END_OF_RECOVERY 0x90
78 #define XLOG_FPI_FOR_HINT 0xA0
79 #define XLOG_FPI 0xB0
80 /* 0xC0 is used in Postgres 9.5-11 */
81 #define XLOG_OVERWRITE_CONTRECORD 0xD0
82 #define XLOG_CHECKPOINT_REDO 0xE0
83 
84 
85 /*
86  * System status indicator. Note this is stored in pg_control; if you change
87  * it, you must bump PG_CONTROL_VERSION
88  */
89 typedef enum DBState
90 {
99 
100 /*
101  * Contents of pg_control.
102  */
103 
104 typedef struct ControlFileData
105 {
106  /*
107  * Unique system identifier --- to ensure we match up xlog files with the
108  * installation that produced them.
109  */
111 
112  /*
113  * Version identifier information. Keep these fields at the same offset,
114  * especially pg_control_version; they won't be real useful if they move
115  * around. (For historical reasons they must be 8 bytes into the file
116  * rather than immediately at the front.)
117  *
118  * pg_control_version identifies the format of pg_control itself.
119  * catalog_version_no identifies the format of the system catalogs.
120  *
121  * There are additional version identifiers in individual files; for
122  * example, WAL logs contain per-page magic numbers that can serve as
123  * version cues for the WAL log.
124  */
125  uint32 pg_control_version; /* PG_CONTROL_VERSION */
126  uint32 catalog_version_no; /* see catversion.h */
127 
128  /*
129  * System status data
130  */
131  DBState state; /* see enum above */
132  pg_time_t time; /* time stamp of last pg_control update */
133  XLogRecPtr checkPoint; /* last check point record ptr */
134 
135  CheckPoint checkPointCopy; /* copy of last check point record */
136 
137  XLogRecPtr unloggedLSN; /* current fake LSN value, for unlogged rels */
138 
139  /*
140  * These two values determine the minimum point we must recover up to
141  * before starting up:
142  *
143  * minRecoveryPoint is updated to the latest replayed LSN whenever we
144  * flush a data change during archive recovery. That guards against
145  * starting archive recovery, aborting it, and restarting with an earlier
146  * stop location. If we've already flushed data changes from WAL record X
147  * to disk, we mustn't start up until we reach X again. Zero when not
148  * doing archive recovery.
149  *
150  * backupStartPoint is the redo pointer of the backup start checkpoint, if
151  * we are recovering from an online backup and haven't reached the end of
152  * backup yet. It is reset to zero when the end of backup is reached, and
153  * we mustn't start up before that. A boolean would suffice otherwise, but
154  * we use the redo pointer as a cross-check when we see an end-of-backup
155  * record, to make sure the end-of-backup record corresponds the base
156  * backup we're recovering from.
157  *
158  * backupEndPoint is the backup end location, if we are recovering from an
159  * online backup which was taken from the standby and haven't reached the
160  * end of backup yet. It is initialized to the minimum recovery point in
161  * pg_control which was backed up last. It is reset to zero when the end
162  * of backup is reached, and we mustn't start up before that.
163  *
164  * If backupEndRequired is true, we know for sure that we're restoring
165  * from a backup, and must see a backup-end record before we can safely
166  * start up.
167  */
173 
174  /*
175  * Parameter settings that determine if the WAL can be used for archival
176  * or hot standby.
177  */
186 
187  /*
188  * This data is used to check for hardware-architecture compatibility of
189  * the database and the backend executable. We need not check endianness
190  * explicitly, since the pg_control version will surely look wrong to a
191  * machine of different endianness, but we do need to worry about MAXALIGN
192  * and floating-point format. (Note: storage layout nominally also
193  * depends on SHORTALIGN and INTALIGN, but in practice these are the same
194  * on all architectures of interest.)
195  *
196  * Testing just one double value is not a very bulletproof test for
197  * floating-point compatibility, but it will catch most cases.
198  */
199  uint32 maxAlign; /* alignment requirement for tuples */
200  double floatFormat; /* constant 1234567.0 */
201 #define FLOATFORMAT_VALUE 1234567.0
202 
203  /*
204  * This data is used to make sure that configuration of this database is
205  * compatible with the backend executable.
206  */
207  uint32 blcksz; /* data block size for this DB */
208  uint32 relseg_size; /* blocks per segment of large relation */
209 
210  uint32 xlog_blcksz; /* block size within WAL files */
211  uint32 xlog_seg_size; /* size of each WAL segment */
212 
213  uint32 nameDataLen; /* catalog name field width */
214  uint32 indexMaxKeys; /* max number of columns in an index */
215 
216  uint32 toast_max_chunk_size; /* chunk size in TOAST tables */
217  uint32 loblksize; /* chunk size in pg_largeobject */
218 
219  bool float8ByVal; /* float8, int8, etc pass-by-value? */
220 
221  /* Are data pages protected by checksums? Zero if no checksum version */
223 
224  /*
225  * Random nonce, used in authentication requests that need to proceed
226  * based on values that are cluster-unique, like a SASL exchange that
227  * failed at an early stage.
228  */
230 
231  /* CRC of all above ... MUST BE LAST! */
234 
235 /*
236  * Maximum safe value of sizeof(ControlFileData). For reliability's sake,
237  * it's critical that pg_control updates be atomic writes. That generally
238  * means the active data can't be more than one disk sector, which is 512
239  * bytes on common hardware. Be very careful about raising this limit.
240  */
241 #define PG_CONTROL_MAX_SAFE_SIZE 512
242 
243 /*
244  * Physical size of the pg_control file. Note that this is considerably
245  * bigger than the actually used size (ie, sizeof(ControlFileData)).
246  * The idea is to keep the physical size constant independent of format
247  * changes, so that ReadControlFile will deliver a suitable wrong-version
248  * message instead of a read error if it's looking at an incompatible file.
249  */
250 #define PG_CONTROL_FILE_SIZE 8192
251 
252 /*
253  * Ensure that the size of the pg_control data structure is sane.
254  */
256  "pg_control is too large for atomic disk writes");
258  "sizeof(ControlFileData) exceeds PG_CONTROL_FILE_SIZE");
259 
260 #endif /* PG_CONTROL_H */
unsigned int uint32
Definition: c.h:506
uint32 MultiXactOffset
Definition: c.h:655
TransactionId MultiXactId
Definition: c.h:653
uint32 TransactionId
Definition: c.h:643
struct ControlFileData ControlFileData
StaticAssertDecl(sizeof(ControlFileData)<=PG_CONTROL_MAX_SAFE_SIZE, "pg_control is too large for atomic disk writes")
#define PG_CONTROL_MAX_SAFE_SIZE
Definition: pg_control.h:241
struct CheckPoint CheckPoint
#define MOCK_AUTH_NONCE_LEN
Definition: pg_control.h:28
DBState
Definition: pg_control.h:90
@ DB_IN_PRODUCTION
Definition: pg_control.h:97
@ DB_STARTUP
Definition: pg_control.h:91
@ DB_SHUTDOWNING
Definition: pg_control.h:94
@ DB_IN_ARCHIVE_RECOVERY
Definition: pg_control.h:96
@ DB_SHUTDOWNED_IN_RECOVERY
Definition: pg_control.h:93
@ DB_SHUTDOWNED
Definition: pg_control.h:92
@ DB_IN_CRASH_RECOVERY
Definition: pg_control.h:95
#define PG_CONTROL_FILE_SIZE
Definition: pg_control.h:250
uint32 pg_crc32c
Definition: pg_crc32c.h:38
int64 pg_time_t
Definition: pgtime.h:23
unsigned int Oid
Definition: postgres_ext.h:31
Oid oldestMultiDB
Definition: pg_control.h:51
MultiXactId oldestMulti
Definition: pg_control.h:50
MultiXactOffset nextMultiOffset
Definition: pg_control.h:47
TransactionId newestCommitTsXid
Definition: pg_control.h:55
TransactionId oldestXid
Definition: pg_control.h:48
TimeLineID PrevTimeLineID
Definition: pg_control.h:40
TimeLineID ThisTimeLineID
Definition: pg_control.h:39
Oid nextOid
Definition: pg_control.h:45
TransactionId oldestActiveXid
Definition: pg_control.h:64
bool fullPageWrites
Definition: pg_control.h:42
MultiXactId nextMulti
Definition: pg_control.h:46
FullTransactionId nextXid
Definition: pg_control.h:44
TransactionId oldestCommitTsXid
Definition: pg_control.h:53
pg_time_t time
Definition: pg_control.h:52
int wal_level
Definition: pg_control.h:43
XLogRecPtr redo
Definition: pg_control.h:37
Oid oldestXidDB
Definition: pg_control.h:49
char mock_authentication_nonce[MOCK_AUTH_NONCE_LEN]
Definition: pg_control.h:229
int max_worker_processes
Definition: pg_control.h:181
uint32 pg_control_version
Definition: pg_control.h:125
uint32 xlog_seg_size
Definition: pg_control.h:211
XLogRecPtr backupStartPoint
Definition: pg_control.h:170
bool track_commit_timestamp
Definition: pg_control.h:185
bool backupEndRequired
Definition: pg_control.h:172
int max_locks_per_xact
Definition: pg_control.h:184
uint32 nameDataLen
Definition: pg_control.h:213
CheckPoint checkPointCopy
Definition: pg_control.h:135
XLogRecPtr backupEndPoint
Definition: pg_control.h:171
XLogRecPtr minRecoveryPoint
Definition: pg_control.h:168
uint32 data_checksum_version
Definition: pg_control.h:222
XLogRecPtr unloggedLSN
Definition: pg_control.h:137
uint32 indexMaxKeys
Definition: pg_control.h:214
uint32 relseg_size
Definition: pg_control.h:208
pg_time_t time
Definition: pg_control.h:132
XLogRecPtr checkPoint
Definition: pg_control.h:133
uint64 system_identifier
Definition: pg_control.h:110
uint32 catalog_version_no
Definition: pg_control.h:126
double floatFormat
Definition: pg_control.h:200
int max_prepared_xacts
Definition: pg_control.h:183
uint32 xlog_blcksz
Definition: pg_control.h:210
TimeLineID minRecoveryPointTLI
Definition: pg_control.h:169
uint32 loblksize
Definition: pg_control.h:217
pg_crc32c crc
Definition: pg_control.h:232
uint32 toast_max_chunk_size
Definition: pg_control.h:216
uint64 XLogRecPtr
Definition: xlogdefs.h:21
uint32 TimeLineID
Definition: xlogdefs.h:59