摘要

事務日志是數據庫的重要組成部分，存儲了數據庫系統中所有更改和操作的歷史，以確保數據庫不會因為故障(例如掉電或其他導致服務器崩潰的故障)而丟失數據。在PostgreSQL(以下簡稱PG)中，事務日志文件稱為Write Ahead Log（以下簡稱WAL）。

本文對PG中事務日志文件的結構進行了簡要的剖析，內容包括WAL基本術語、WAL文件組成、WAL segment file內部結構和內容剖析、XLOG Record內存組織以及 pg_waldump 工具簡介。本篇是第一部分，內容包括WAL基本術語、WAL文件組成以及WAL segment file的內部結構。

一、WAL基本術語

為了更好的理解WAL和便于溝通，有必要首先對相關的WAL術語進行簡要的介紹。

1、REDO log

Redo log通常稱為重做日志，在寫入數據文件前，每個變更都會先行寫入到Redo log中。其用途和意義在于存儲數據庫的所有修改歷史，用于數據庫故障恢復（Recovery）、增量備份（Incremental Backup）、PITR(Point In Time Recovery)和復制（Replication）。

2、WAL segment file

為了便于管理，PG把事務日志文件劃分為N個segment，每個segment稱為WAL segment file，每個WAL segment file大小默認為16MB。

3、XLOG Record

這是一個邏輯概念，可以理解為PG中的每一個變更都對應一條XLOG Record，這些XLOG Record存儲在WAL segment file中。PG讀取這些XLOG Record進行故障恢復/PITR等操作。

4、WAL buffer

WA緩沖區，不管是WAL segment file的header還是XLOG Record都會先行寫入到WAL緩沖區中，在"合適的時候"再通過WAL writer寫入到WAL segment file中。

5、LSN

LSN即日志序列號Log Sequence Number。表示XLOG record記錄寫入到事務日志中位置。LSN的值為無符號64位整型（uint64）。在事務日志中，LSN單調遞增且唯一。

6、checkpointer

checkpointer是PG中的一個后臺進程，該進程周期性地執行checkpoint。當執行checkpoint時，該進程會把包含checkpoint信息的XLOG Record寫入到當前的WAL segment file中，該XLOG Record記錄包含了最新Redo pint的位置。

7、checkpoint

檢查點checkpoint由checkpointer進程執行，主要的處理流程如下：

1. 獲取Redo point，構造包含此Redo point檢查點（詳細請參考Checkpoint結構體）信息的XLOG Record并寫入到WAL segment file中；
2. 刷新Dirty Page到磁盤上；
3. 更新Redo point等信息到 pg_control 文件中。

8、REDO point

REDO point是PG啟動恢復的起始點，是最后一次checkpoint啟動時事務日志文件的末尾亦即寫入Checkpoint XLOG Record時的位置（這里的位置可以理解為事務日志文件中偏移量）。

9、 pg_control

pg_control 是磁盤上的物理文件，保存檢查點的基本信息，在數據庫恢復中使用，可通過命令 pg_controldata 查看該文件中的內容。

二、WAL文件組成

如前所述，事務日志存儲了數據庫系統中所有更改和操作的歷史，隨著數據庫的運行，事務日志大小不斷的增長，那么事務日志有大小限制嗎？在PG中，答案是肯定的：大小有限制。

PG使用無符號64bit整型（uint64）作為事務日志文件的尋址空間，理論上，PG的事務日志空間最大為2^64Bytes(即16EB)。這個大小有多大呢？假設某個數據庫比較繁忙，每天可以產生16TB的日志文件，那么要達到事務日志文件大小的上限需要的時間是1024*1024/365天≈2800年。也就是說，雖然大小有限制，但從現階段來看已然足夠了。

顯然，對于16EB的文件，OS是無法高效管理的，為此，PG把事務日志文件劃分為N個大小為16M(默認值)的WAL segment file，其總體結構如下圖所示：

圖一 事務日志總體結構

1、WAL segment file

WAL segment file文件名稱為24個字符，由3部分組成，每個部分是8個字符，每個字符是一個16進制值（即0~F）。每一部分的解析如下（在WAL segment file文件大小為16MB的情況下）：

1. 第1部分是TimeLineID，取值范圍是0x00000000 -> 0xFFFFFFFF
2. 第2部分是邏輯文件ID，取值范圍是0x00000000 -> 0xFFFFFFFF
3. 第3部分是物理文件ID，取值范圍是0x00000000 -> 0x000000FF

邏輯文件ID、物理文件ID和文件大小這三部分的組合，實現了64bit的尋找空間：

1. 邏輯文件ID是32bit的uint32（unsigned int 32bit）
2. 物理文件ID是8bit的unit8
3. 16M的文件大小是24bit的unit24

三者共同組成unit64（32+8+24），達到最大64bit的文件尋址空間。

2、再談LSN

事務日志文件的LSN表示XLOG Record記錄寫入到事務日志文件中的位置。LSN可以理解為XLOG Record在事務日志文件中的偏移(Offset)。

LSN由3部分組成，分別是邏輯文件ID，物理文件ID和文件內偏移。如LSN：1/4288E228，其中1為邏輯文件ID，42為物理文件ID，88E228為WAL segment file文件內偏移（注：3Bytes的尋找空間為16MB）。

按此規則,給定一個LSN，很容易根據LSN號推算得到其對應的日志文件(假定時間線TimeLineID為1)。

如：LSN 1/4288E228對應的WAL segment file文件為00000001 00000001 00000042，該文件名稱的前8位為時間線ID（00000001），中間8位（00000001）為邏輯文件ID，最后8位（00000042）為物理文件ID。

另外，PG也提供了相應的函數根據LSN獲取日志文件名：

testdb=# SELECT pg_walfile_name('1/4288E228');
     pg_walfile_name      
--------------------------
 000000010000000100000042
(1 row)

三、WAL segment file內部結構

WAL segment file默認大小為16MB,其內部結構如下圖所示：

圖二 WAL segment file內部結構

1、WAL segment file

WAL segment file內部劃分為N個page(Block)，每個page大小為8192 Bytes即8K，每個WAL segment file第1個page的header在PG源碼中相應的數據結構是XLogLongPageHeaderData，后續其他page的header對應的數據結構是XLogPageHeaderData。在一個page中，page header之后是N個XLOG Record。

2、XLOG Record

XLOG Record由兩部分組成，第一部分是XLOG Record的頭部信息，大小固定（24 Bytes），對應的結構體是XLogRecord；第二部分是XLOG Record data。

XLOG Record的整體布局如下:

頭部數據(固定大小的XLogRecord結構體)
XLogRecordBlockHeader 結構體
XLogRecordBlockHeader 結構體
...
XLogRecordDataHeader[Short|Long] 結構體
block data
block data
...
main data

XLOG Record按存儲的數據內容來劃分，大體可以分為三類：

1. Record for backup block：存儲full-write-page的block，這種類型Record是為了解決page部分寫的問題。在checkpoint完成后第一次修改數據page，在記錄此變更寫入事務日志文件時整頁寫入（需設置相應的初始化參數，默認為打開）；
2. Record for tuple data block：存儲page中的tuple變更，使用這種類型的Record記錄；
3. Record for Checkpoint：在checkpoint發生時，在事務日志文件中記錄checkpoint信息(其中包括Redo point)。

其中XLOG Record data是存儲實際數據的地方，由以下幾部分組成：

1. 0..N個XLogRecordBlockHeader，每一個XLogRecordBlockHeader對應一個block data；
2. XLogRecordDataHeader[Short|Long]，如數據大小<256 Bytes，則使用Short格式，否則使用Long格式；
3. block data：full-write-page data和tuple data。對于full-write-page data，如啟用了壓縮，則數據壓縮存儲，壓縮后該page相關的元數據存儲在XLogRecordBlockCompressHeader中；
4. main data： /checkpoint等日志數據.

以INSERT數據為例，在插入數據時的XLOG Record data內部結構如下圖所示:

圖三 XLOG Record data for DML Statement

3、數據結構

1、XLogPageHeaderData結構體定義

/*
 * Each page of XLOG file has a header like this:
 * 每一個事務日志文件的page都有頭部信息,結構如下:
 */
//可作為WAL版本信息
#define XLOG_PAGE_MAGIC 0xD098  /* can be used as WAL version indicator */
typedef struct XLogPageHeaderData
{
    //WAL版本信息,PG V11.1 --> 0xD98
    uint16      xlp_magic;      /* magic value for correctness checks */
    //標記位(詳見下面說明)
    uint16      xlp_info;       /* flag bits, see below */
    //page中第一個XLOG Record的TimeLineID,類型為uint32
    TimeLineID  xlp_tli;        /* TimeLineID of first record on page */
    //page的XLOG地址(在事務日志中的偏移),類型為uint64
    XLogRecPtr  xlp_pageaddr;   /* XLOG address of this page */
    /*
     * When there is not enough space on current page for whole record, we
     * continue on the next page.  xlp_rem_len is the number of bytes
     * remaining from a previous page.
     * 如果當前頁的空間不足以存儲整個XLOG Record,在下一個頁面中存儲余下的數據
     * xlp_rem_len表示上一頁XLOG Record剩余部分的大小
     *
     * Note that xl_rem_len includes backup-block data; that is, it tracks
     * xl_tot_len not xl_len in the initial header.  Also note that the
     * continuation data isn't necessarily aligned.
     * 注意xl_rem_len包含backup-block data(full-page-write);
     * 也就是說在初始的頭部信息中跟蹤的是xl_tot_len而不是xl_len.
     * 另外要注意的是剩余的數據不需要對齊.
     */
    //上一頁空間不夠存儲XLOG Record,該Record在本頁繼續存儲占用的空間大小
    uint32      xlp_rem_len;    /* total len of remaining data for record */
} XLogPageHeaderData;
#define SizeOfXLogShortPHD  MAXALIGN(sizeof(XLogPageHeaderData))
typedef XLogPageHeaderData *XLogPageHeader;

2、XLogLongPageHeaderData結構體定義

/*
 * When the XLP_LONG_HEADER flag is set, we store additional fields in the
 * page header.  (This is ordinarily done just in the first page of an
 * XLOG file.)  The additional fields serve to identify the file accurately.
 * 如設置了XLP_LONG_HEADER標記,在page header中存儲額外的字段.
 * (通常在每個事務日志文件也就是segment file的的第一個page中存在).
 * 附加字段用于準確識別文件。
 */
typedef struct XLogLongPageHeaderData
{
    //標準的頭部域字段
    XLogPageHeaderData std;     /* standard header fields */
    //pg_control中的系統標識碼
    uint64      xlp_sysid;      /* system identifier from pg_control */
    //交叉檢查
    uint32      xlp_seg_size;   /* just as a cross-check */
    //交叉檢查
    uint32      xlp_xlog_blcksz;    /* just as a cross-check */
} XLogLongPageHeaderData;
#define SizeOfXLogLongPHD   MAXALIGN(sizeof(XLogLongPageHeaderData))
//指針
typedef XLogLongPageHeaderData *XLogLongPageHeader;
/* When record crosses page boundary, set this flag in new page's header */
//如果XLOG Record跨越page邊界,在新page header中設置該標志位
#define XLP_FIRST_IS_CONTRECORD     0x0001
//該標志位標明是"long"頁頭
/* This flag indicates a "long" page header */
#define XLP_LONG_HEADER             0x0002
/* This flag indicates backup blocks starting in this page are optional */
//該標志位標明從該頁起始的backup blocks是可選的(不一定存在)
#define XLP_BKP_REMOVABLE           0x0004
//xlp_info中所有定義的標志位(用于page header的有效性檢查)
/* All defined flag bits in xlp_info (used for validity checking of header) */
#define XLP_ALL_FLAGS               0x0007
#define XLogPageHeaderSize(hdr)     \
    (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)

3、XLogRecord結構體定義

/*
 * The overall layout of an XLOG record is:
 *      Fixed-size header (XLogRecord struct)
 *      XLogRecordBlockHeader struct
 *      XLogRecordBlockHeader struct
 *      ...
 *      XLogRecordDataHeader[Short|Long] struct
 *      block data
 *      block data
 *      ...
 *      main data
 * XLOG record的整體布局如下:
 *         固定大小的頭部(XLogRecord 結構體)
 *        XLogRecordBlockHeader 結構體
 *        XLogRecordBlockHeader 結構體
 *        ...
 *        XLogRecordDataHeader[Short|Long] 結構體
 *        block data
 *        block data
 *        ...
 *        main data
 *
 * There can be zero or more XLogRecordBlockHeaders, and 0 or more bytes of
 * rmgr-specific data not associated with a block.  XLogRecord structs
 * always start on MAXALIGN boundaries in the WAL files, but the rest of
 * the fields are not aligned.
 * 其中,XLogRecordBlockHeaders可能有0或者多個,與block無關的0或多個字節的rmgr-specific數據
 * XLogRecord通常在WAL文件的MAXALIGN邊界起寫入,但后續的字段并沒有對齊
 *
 * The XLogRecordBlockHeader, XLogRecordDataHeaderShort and
 * XLogRecordDataHeaderLong structs all begin with a single 'id' byte. It's
 * used to distinguish between block references, and the main data structs.
 * XLogRecordBlockHeader/XLogRecordDataHeaderShort/XLogRecordDataHeaderLong開頭是占用1個字節的"id".
 * 用于區分block依賴和main data結構體.
 */
typedef struct XLogRecord
{
    //record的大小
    uint32      xl_tot_len;     /* total len of entire record */
    //xact id
    TransactionId xl_xid;       /* xact id */
    //指向log中的前一條記錄
    XLogRecPtr  xl_prev;        /* ptr to previous record in log */
    //標識位,詳見下面的說明
    uint8       xl_info;        /* flag bits, see below */
    //該記錄的資源管理器
    RmgrId      xl_rmid;        /* resource manager for this record */
    /* 2 bytes of padding here, initialize to zero */
    //2個字節的crc校驗位,初始化為0
    pg_crc32c   xl_crc;         /* CRC for this record */
    /* XLogRecordBlockHeaders and XLogRecordDataHeader follow, no padding */
    //接下來是XLogRecordBlockHeaders和XLogRecordDataHeader
} XLogRecord;
//宏定義:XLogRecord大小
#define SizeOfXLogRecord    (offsetof(XLogRecord, xl_crc) + sizeof(pg_crc32c))
/*
 * The high 4 bits in xl_info may be used freely by rmgr. The
 * XLR_SPECIAL_REL_UPDATE and XLR_CHECK_CONSISTENCY bits can be passed by
 * XLogInsert caller. The rest are set internally by XLogInsert.
 * xl_info的高4位由rmgr自由使用.
 * XLR_SPECIAL_REL_UPDATE和XLR_CHECK_CONSISTENCY由XLogInsert函數的調用者傳入.
 * 其余由XLogInsert內部使用.
 */
#define XLR_INFO_MASK           0x0F
#define XLR_RMGR_INFO_MASK      0xF0
/*
 * If a WAL record modifies any relation files, in ways not covered by the
 * usual block references, this flag is set. This is not used for anything
 * by PostgreSQL itself, but it allows external tools that read WAL and keep
 * track of modified blocks to recognize such special record types.
 * 如果WAL記錄使用特殊的方式(不涉及通常塊引用)更新了關系的存儲文件,設置此標記.
 * PostgreSQL本身并不使用這種方法，但它允許外部工具讀取WAL并跟蹤修改后的塊，
 *   以識別這種特殊的記錄類型。
 */
#define XLR_SPECIAL_REL_UPDATE  0x01
/*
 * Enforces consistency checks of replayed WAL at recovery. If enabled,
 * each record will log a full-page write for each block modified by the
 * record and will reuse it afterwards for consistency checks. The caller
 * of XLogInsert can use this value if necessary, but if
 * wal_consistency_checking is enabled for a rmgr this is set unconditionally.
 * 在恢復時強制執行一致性檢查.
 * 如啟用此功能,每個記錄將為記錄修改的每個塊記錄一個完整的頁面寫操作，并在以后重用它進行一致性檢查。
 * 在需要時,XLogInsert的調用者可使用此標記,但如果rmgr啟用了wal_consistency_checking,
 *   則會無條件執行一致性檢查.
 */
#define XLR_CHECK_CONSISTENCY   0x02

4、XLogRecordBlockHeader結構體定義

/*
 * Header info for block data appended to an XLOG record.
 * 追加到XLOG record中block data的頭部信息
 *
 * 'data_length' is the length of the rmgr-specific payload data associated
 * with this block. It does not include the possible full page image, nor
 * XLogRecordBlockHeader struct itself.
 * 'data_length'是與此塊關聯的rmgr特定payload data的長度。
 * 它不包括可能的full page image，也不包括XLogRecordBlockHeader結構體本身。
 *
 * Note that we don't attempt to align the XLogRecordBlockHeader struct!
 * So, the struct must be copied to aligned local storage before use.
 * 注意:我們不打算嘗試對齊XLogRecordBlockHeader結構體!
 * 因此,在使用前,XLogRecordBlockHeader必須拷貝到對齊的本地存儲中.
 */
typedef struct XLogRecordBlockHeader
{
    //塊引用ID
    uint8       id;             /* block reference ID */
    //在關系中使用的fork和flags
    uint8       fork_flags;     /* fork within the relation, and flags */
    //payload字節大小
    uint16      data_length;    /* number of payload bytes (not including page
                                 * image) */
    /* If BKPBLOCK_HAS_IMAGE, an XLogRecordBlockImageHeader struct follows */
/* If BKPBLOCK_SAME_REL is not set, a RelFileNode follows */
/* BlockNumber follows */
    //如BKPBLOCK_HAS_IMAGE,后續為XLogRecordBlockImageHeader結構體    
    //如BKPBLOCK_SAME_REL沒有設置,則為RelFileNode
    //后續為BlockNumber
} XLogRecordBlockHeader;
#define SizeOfXLogRecordBlockHeader (offsetof(XLogRecordBlockHeader, data_length) + sizeof(uint16))

5、XLogRecordDataHeader[Short|Long]結構體定義

/*
 * XLogRecordDataHeaderShort/Long are used for the "main data" portion of
 * the record. If the length of the data is less than 256 bytes, the short
 * form is used, with a single byte to hold the length. Otherwise the long
 * form is used.
 * XLogRecordDataHeaderShort/Long用于記錄的“main data”部分。
 * 如果數據的長度小于256字節，則使用短格式，用一個字節保存長度。
 * 否則使用長形式。
 *
 * (These structs are currently not used in the code, they are here just for
 * documentation purposes).
 * (這些結構體不會再代碼中使用,在這里是為了文檔記錄的目的)
 */
typedef struct XLogRecordDataHeaderShort
{
    uint8       id;             /* XLR_BLOCK_ID_DATA_SHORT */
    uint8       data_length;    /* number of payload bytes */
}           XLogRecordDataHeaderShort;
#define SizeOfXLogRecordDataHeaderShort (sizeof(uint8) * 2)
typedef struct XLogRecordDataHeaderLong
{
    uint8       id;             /* XLR_BLOCK_ID_DATA_LONG */
    /* followed by uint32 data_length, unaligned */
    //接下來是無符號32位整型的data_length(未對齊)
}           XLogRecordDataHeaderLong;
#define SizeOfXLogRecordDataHeaderLong (sizeof(uint8) + sizeof(uint32))
/*
 * Block IDs used to distinguish different kinds of record fragments. Block
 * references are numbered from 0 to XLR_MAX_BLOCK_ID. A rmgr is free to use
 * any ID number in that range (although you should stick to small numbers,
 * because the WAL machinery is optimized for that case). A couple of ID
 * numbers are reserved to denote the "main" data portion of the record.
 * 塊id用于區分不同類型的記錄片段。
 * 塊引用編號從0到XLR_MAX_BLOCK_ID。
 * rmgr可以自由使用該范圍內的任何ID號
 *   (盡管您應該堅持使用較小的數字，因為WAL機制針對這種情況進行了優化)。
 * 保留兩個ID號來表示記錄的“main”數據部分。
 *
 * The maximum is currently set at 32, quite arbitrarily. Most records only
 * need a handful of block references, but there are a few exceptions that
 * need more.
 * 目前的最大值是32，非常隨意。
 * 大多數記錄只需要少數塊引用，但也有少數的例外，需要更多。
 */
#define XLR_MAX_BLOCK_ID            32
#define XLR_BLOCK_ID_DATA_SHORT     255
#define XLR_BLOCK_ID_DATA_LONG      254
#define XLR_BLOCK_ID_ORIGIN         253
#endif                          /* XLOGRECORD_H */

6、 xl_heap_header 結構體定義

/*
 * We don't store the whole fixed part (HeapTupleHeaderData) of an inserted
 * or updated tuple in WAL; we can save a few bytes by reconstructing the
 * fields that are available elsewhere in the WAL record, or perhaps just
 * plain needn't be reconstructed.  These are the fields we must store.
 * NOTE: t_hoff could be recomputed, but we may as well store it because
 * it will come for free due to alignment considerations.
 * PG不會在WAL中存儲插入/更新的元組的全部固定部分(HeapTupleHeaderData);
 *   我們可以通過重新構造在WAL記錄中可用的一些字段來節省一些空間,或者直接扁平化處理。
 * 這些都是我們必須存儲的字段。
 * 注意:t_hoff可以重新計算，但我們也需要存儲它，因為出于對齊的考慮,會被析構。
 */
typedef struct xl_heap_header
{
    uint16      t_infomask2;//t_infomask2標記
    uint16      t_infomask;//t_infomask標記
    uint8       t_hoff;//t_hoff
} xl_heap_header;
//HeapHeader的大小
#define SizeOfHeapHeader    (offsetof(xl_heap_header, t_hoff) + sizeof(uint8))
7)    xl_heap_insert結構體定義
/*
 * xl_heap_insert/xl_heap_multi_insert flag values, 8 bits are available.
 */
/* PD_ALL_VISIBLE was cleared */
#define XLH_INSERT_ALL_VISIBLE_CLEARED          (1<<0)
#define XLH_INSERT_LAST_IN_MULTI                (1<<1)
#define XLH_INSERT_IS_SPECULATIVE               (1<<2)
#define XLH_INSERT_CONTAINS_NEW_TUPLE           (1<<3)
/* This is what we need to know about insert */
//這是在插入時需要獲知的信息
typedef struct xl_heap_insert
{
    //已成功插入的元組的偏移
    OffsetNumber offnum;        /* inserted tuple's offset */
    uint8       flags;            //標記
    /* xl_heap_header & TUPLE DATA in backup block 0 */
    //xl_heap_header & TUPLE DATA在備份塊0中
} xl_heap_insert;
//xl_heap_insert大小
#define SizeOfHeapInsert    (offsetof(xl_heap_insert, flags) + sizeof(uint8))

四、參考資料

1. Write Ahead Logging — WAL： http://www.interdb.jp/pg/pgsql09.html
2. PG Source Code： https://doxygen.postgresql.org
3. WAL Internals Of PostgreSQL： https://www.pgcon.org/2012/schedule/attachments/258_212_Internals%20Of%20PostgreSQL%20Wal.pdf
4. 關于結構體占用空間大小總結： https://blog.csdn.net/Netown_Ethereal/article/details/38898003
5. PG 11 Document： https://www.postgresql.org/docs/11/pgwaldump.html