granicus.if.org Git - postgresql/blob - src/include/catalog/pg_control.h

   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-2017, 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/xlogdefs.h"
  19 #include "pgtime.h"                             /* for pg_time_t */
  20 #include "port/pg_crc32c.h"
  21
  22
  23 #define MOCK_AUTH_NONCE_LEN             32
  24
  25 /* Version identifier for this pg_control format */
  26 #define PG_CONTROL_VERSION      1002
  27
  28 /*
  29  * Body of CheckPoint XLOG records.  This is declared here because we keep
  30  * a copy of the latest one in pg_control for possible disaster recovery.
  31  * Changing this struct requires a PG_CONTROL_VERSION bump.
  32  */
  33 typedef struct CheckPoint
  34 {
  35         XLogRecPtr      redo;                   /* next RecPtr available when we began to
  36                                                                  * create CheckPoint (i.e. REDO start point) */
  37         TimeLineID      ThisTimeLineID; /* current TLI */
  38         TimeLineID      PrevTimeLineID; /* previous TLI, if this record begins a new
  39                                                                  * timeline (equals ThisTimeLineID otherwise) */
  40         bool            fullPageWrites; /* current full_page_writes */
  41         uint32          nextXidEpoch;   /* higher-order bits of nextXid */
  42         TransactionId nextXid;          /* next free XID */
  43         Oid                     nextOid;                /* next free OID */
  44         MultiXactId nextMulti;          /* next free MultiXactId */
  45         MultiXactOffset nextMultiOffset;        /* next free MultiXact offset */
  46         TransactionId oldestXid;        /* cluster-wide minimum datfrozenxid */
  47         Oid                     oldestXidDB;    /* database with minimum datfrozenxid */
  48         MultiXactId oldestMulti;        /* cluster-wide minimum datminmxid */
  49         Oid                     oldestMultiDB;  /* database with minimum datminmxid */
  50         pg_time_t       time;                   /* time stamp of checkpoint */
  51         TransactionId oldestCommitTsXid;        /* oldest Xid with valid commit
  52                                                                                  * timestamp */
  53         TransactionId newestCommitTsXid;        /* newest Xid with valid commit
  54                                                                                  * timestamp */
  55
  56         /*
  57          * Oldest XID still running. This is only needed to initialize hot standby
  58          * mode from an online checkpoint, so we only bother calculating this for
  59          * online checkpoints and only when wal_level is replica. Otherwise it's
  60          * set to InvalidTransactionId.
  61          */
  62         TransactionId oldestActiveXid;
  63 } CheckPoint;
  64
  65 /* XLOG info values for XLOG rmgr */
  66 #define XLOG_CHECKPOINT_SHUTDOWN                0x00
  67 #define XLOG_CHECKPOINT_ONLINE                  0x10
  68 #define XLOG_NOOP                                               0x20
  69 #define XLOG_NEXTOID                                    0x30
  70 #define XLOG_SWITCH                                             0x40
  71 #define XLOG_BACKUP_END                                 0x50
  72 #define XLOG_PARAMETER_CHANGE                   0x60
  73 #define XLOG_RESTORE_POINT                              0x70
  74 #define XLOG_FPW_CHANGE                                 0x80
  75 #define XLOG_END_OF_RECOVERY                    0x90
  76 #define XLOG_FPI_FOR_HINT                               0xA0
  77 #define XLOG_FPI                                                0xB0
  78
  79
  80 /*
  81  * System status indicator.  Note this is stored in pg_control; if you change
  82  * it, you must bump PG_CONTROL_VERSION
  83  */
  84 typedef enum DBState
  85 {
  86         DB_STARTUP = 0,
  87         DB_SHUTDOWNED,
  88         DB_SHUTDOWNED_IN_RECOVERY,
  89         DB_SHUTDOWNING,
  90         DB_IN_CRASH_RECOVERY,
  91         DB_IN_ARCHIVE_RECOVERY,
  92         DB_IN_PRODUCTION
  93 } DBState;
  94
  95 /*
  96  * Contents of pg_control.
  97  *
  98  * NOTE: try to keep this under 512 bytes so that it will fit on one physical
  99  * sector of typical disk drives.  This reduces the odds of corruption due to
 100  * power failure midway through a write.
 101  */
 102
 103 typedef struct ControlFileData
 104 {
 105         /*
 106          * Unique system identifier --- to ensure we match up xlog files with the
 107          * installation that produced them.
 108          */
 109         uint64          system_identifier;
 110
 111         /*
 112          * Version identifier information.  Keep these fields at the same offset,
 113          * especially pg_control_version; they won't be real useful if they move
 114          * around.  (For historical reasons they must be 8 bytes into the file
 115          * rather than immediately at the front.)
 116          *
 117          * pg_control_version identifies the format of pg_control itself.
 118          * catalog_version_no identifies the format of the system catalogs.
 119          *
 120          * There are additional version identifiers in individual files; for
 121          * example, WAL logs contain per-page magic numbers that can serve as
 122          * version cues for the WAL log.
 123          */
 124         uint32          pg_control_version; /* PG_CONTROL_VERSION */
 125         uint32          catalog_version_no; /* see catversion.h */
 126
 127         /*
 128          * System status data
 129          */
 130         DBState         state;                  /* see enum above */
 131         pg_time_t       time;                   /* time stamp of last pg_control update */
 132         XLogRecPtr      checkPoint;             /* last check point record ptr */
 133         XLogRecPtr      prevCheckPoint; /* previous 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. If it's false, but backupStartPoint is set, a backup_label
 167          * file was found at startup but it may have been a leftover from a stray
 168          * pg_start_backup() call, not accompanied by pg_stop_backup().
 169          */
 170         XLogRecPtr      minRecoveryPoint;
 171         TimeLineID      minRecoveryPointTLI;
 172         XLogRecPtr      backupStartPoint;
 173         XLogRecPtr      backupEndPoint;
 174         bool            backupEndRequired;
 175
 176         /*
 177          * Parameter settings that determine if the WAL can be used for archival
 178          * or hot standby.
 179          */
 180         int                     wal_level;
 181         bool            wal_log_hints;
 182         int                     MaxConnections;
 183         int                     max_worker_processes;
 184         int                     max_prepared_xacts;
 185         int                     max_locks_per_xact;
 186         bool            track_commit_timestamp;
 187
 188         /*
 189          * This data is used to check for hardware-architecture compatibility of
 190          * the database and the backend executable.  We need not check endianness
 191          * explicitly, since the pg_control version will surely look wrong to a
 192          * machine of different endianness, but we do need to worry about MAXALIGN
 193          * and floating-point format.  (Note: storage layout nominally also
 194          * depends on SHORTALIGN and INTALIGN, but in practice these are the same
 195          * on all architectures of interest.)
 196          *
 197          * Testing just one double value is not a very bulletproof test for
 198          * floating-point compatibility, but it will catch most cases.
 199          */
 200         uint32          maxAlign;               /* alignment requirement for tuples */
 201         double          floatFormat;    /* constant 1234567.0 */
 202 #define FLOATFORMAT_VALUE       1234567.0
 203
 204         /*
 205          * This data is used to make sure that configuration of this database is
 206          * compatible with the backend executable.
 207          */
 208         uint32          blcksz;                 /* data block size for this DB */
 209         uint32          relseg_size;    /* blocks per segment of large relation */
 210
 211         uint32          xlog_blcksz;    /* block size within WAL files */
 212         uint32          xlog_seg_size;  /* size of each WAL segment */
 213
 214         uint32          nameDataLen;    /* catalog name field width */
 215         uint32          indexMaxKeys;   /* max number of columns in an index */
 216
 217         uint32          toast_max_chunk_size;   /* chunk size in TOAST tables */
 218         uint32          loblksize;              /* chunk size in pg_largeobject */
 219
 220         /* flags indicating pass-by-value status of various types */
 221         bool            float4ByVal;    /* float4 pass-by-value? */
 222         bool            float8ByVal;    /* float8, int8, etc pass-by-value? */
 223
 224         /* Are data pages protected by checksums? Zero if no checksum version */
 225         uint32          data_checksum_version;
 226
 227         /*
 228          * Random nonce, used in authentication requests that need to proceed
 229          * based on values that are cluster-unique, like a SASL exchange that
 230          * failed at an early stage.
 231          */
 232         char            mock_authentication_nonce[MOCK_AUTH_NONCE_LEN];
 233
 234         /* CRC of all above ... MUST BE LAST! */
 235         pg_crc32c       crc;
 236 } ControlFileData;
 237
 238 /*
 239  * Physical size of the pg_control file.  Note that this is considerably
 240  * bigger than the actually used size (ie, sizeof(ControlFileData)).
 241  * The idea is to keep the physical size constant independent of format
 242  * changes, so that ReadControlFile will deliver a suitable wrong-version
 243  * message instead of a read error if it's looking at an incompatible file.
 244  */
 245 #define PG_CONTROL_SIZE         8192
 246
 247 #endif                                                  /* PG_CONTROL_H */