預寫式日誌（WAL）

為什麼需要日誌

第 4 章提到緩衝池的 steal（未 commit 的髒頁可先寫回）與 no-force（commit 時不必寫回資料頁）策略能把隨機寫入延後、合併， 但也帶來兩個問題：

• steal \(\Rightarrow\) 當機時磁碟上可能有未 commit 交易的修改，需要 undo。

• no-force \(\Rightarrow\) 當機時已 commit 交易的修改可能還沒落盤，需要 redo。

解法是把「發生了什麼修改」循序追加到一個獨立的日誌檔並 fsync——循序寫比隨機寫快一到兩個數量級， 而且一次 fsync 就能讓一批交易持久。資料頁本身可以晚點、合併後再寫。這就是 。

WAL 協定

每筆日誌記錄有一個單調遞增的 （本質上是它在日誌串流中的位元組位移）。 每個資料頁的標頭記錄 pageLSN：最後一次修改這頁的日誌記錄 LSN。系統維護 flushedLSN：已持久化到磁碟的日誌最大 LSN。

日誌記錄的內容

典型記錄欄位：LSN、交易 ID、prevLSN（同一交易前一筆記錄，串成該交易的回溯鏈）、記錄類型、受影響的頁與位移、 修改前映像（before image，供 undo）、修改後映像（after image，供 redo）。 PostgreSQL 因為 MVCC 不需要 undo 日誌，只記 redo 資訊。

Full-Page Write 與 torn page

第 2 章提到：8 KB 頁寫到只保證 4 KB 原子性的磁碟上，斷電可能造成半新半舊的頁。 生理日誌無法對一個損壞的頁做 redo（頁內結構已不可信）。PostgreSQL 的解法是 full-page write（FPW）： 每個 checkpoint 之後，第一次修改某頁時把整頁映像寫進 WAL；復原時直接用該映像覆蓋，再套用後續的增量記錄。 代價是 checkpoint 剛結束時 WAL 量暴增（可用 壓縮 FPI）。 InnoDB 則用 doublewrite buffer：先把頁寫到一塊連續區域、再寫到真正位置，兩者至少有一份完整。

Checkpoint

日誌不能無限成長，復原也不能從創世紀開始重播。Checkpoint 把緩衝池的髒頁寫回磁碟，並記下一個 redo point： 復原只需從此點開始。簡單的做法是暫停所有交易、寫光髒頁——不可接受；實務上用 fuzzy checkpoint： 記下開始時的 LSN，在正常服務的同時慢慢把當時的髒頁寫出，完成後才把 redo point 寫入控制檔（第 11 章 ARIES 會精確處理其正確性）。

Commit 的成本：fsync 與 group commit

一次 在 NVMe 上約 20–100 µs、在雲端網路磁碟上可能數毫秒——若每筆交易都 fsync，吞吐上限就是 1/fsync 延遲。 Group commit：多個同時 commit 的交易共用一次 fsync。PostgreSQL 的做法是：commit 的 backend 若發現有人正在 flush，就等待那次 flush 完成 （）； 可刻意多等一點以湊更多交易。另有背景的 walwriter 定期（，200 ms）寫出 WAL 緩衝區。

PostgreSQL 的 WAL 實體佈局

• WAL 位於 ，切成 16 MB 的段檔（segment）（ 可改），每段內再分 8 KB 頁。

• 檔名 由三個 8 位十六進位數組成：timeline（PITR／failover 後遞增）、log id、segment no。

• LSN 以 的十六進位表示，如 ； 取得目前位置、 對應段檔、 計算位元組差（監控複寫延遲的基礎）。

• ：（只夠當機復原）、（預設；支援串流複寫與 PITR）、（加入邏輯解碼所需資訊）。

• 封存（archiving）： 加 （或 ）把寫滿的段檔複製到外部儲存， 搭配基礎備份即可做 Point-in-Time Recovery。

• 段檔會被回收重用（rename 為未來的檔名）而非刪除，介於 與 之間。

$ pg_waldump -p $PGDATA/pg_wal -s 0/16B3748 -n 4
rmgr: Heap        len (rec/tot):     54/   218, tx:        748, lsn: 0/016B3748, prev 0/016B3710,
      desc: HOT_UPDATE old_xmax: 748, old_off: 2, old_infobits: [], flags: 0x20, new_xmax: 0, new_off: 3,
      blkref #0: rel 1663/16384/16385 blk 0 FPW
rmgr: Transaction len (rec/tot):     34/    34, tx:        748, lsn: 0/016B3828, prev 0/016B3748,
      desc: COMMIT 2026-10-08 10:12:31.448521 CST

第一筆是 heap 的 HOT update（帶 full-page image，因為是 checkpoint 後首次修改該頁），第二筆是 commit 記錄； 串起同一交易的記錄。可加 看各 rmgr 的 WAL 量分佈，是診斷「為什麼 WAL 這麼多」的第一步。

其他系統的日誌設計

• InnoDB：redo log 是固定大小的環狀檔（），寫滿前必須完成 checkpoint； undo 資訊存在 undo tablespace（供 MVCC 與回滾，第 9 章）； 對應 。

• SQLite WAL 模式：修改的整頁追加到 檔， 檔是頁號到 WAL 位置的索引；checkpoint 把頁複製回主檔。 讀者讀 WAL 中的最新版本，寫者不阻塞讀者——一種以頁為粒度的 MVCC。

• RocksDB：每個 memtable 對應一個 WAL，memtable flush 成 SSTable 後 WAL 即可刪除（第 12 章）。

WAL 的其他用途

WAL 是資料庫中「所有變更的全序」，因此順理成章地成為：實體複寫的傳輸內容（第 14 章 streaming replication）、 PITR 的素材、邏輯解碼（logical decoding）與 CDC（Debezium 把 WAL 轉成 Kafka 事件）的來源。 理解 WAL 等於同時理解了復原、複寫與變更擷取。

class LogManager {
 public:
  // 追加記錄到記憶體緩衝區，回傳其 LSN；不保證落盤
  lsn_t Append(const LogRecord &rec);
  // 阻塞直到 flushed_lsn_ >= lsn（commit 與寫髒頁前呼叫）
  void Flush(lsn_t lsn);
  lsn_t FlushedLsn() const { return flushed_lsn_.load(); }
 private:
  void FlusherThread();   // 背景執行緒：定期或被喚醒時 write + fsync，實作 group commit
  std::vector<char> buffer_;  std::mutex mu_;  std::condition_variable cv_;
  std::atomic<lsn_t> next_lsn_{0}, flushed_lsn_{0};
};