// src/backend/access/transam/xact.c
typedef enum TransState {
    TRANS_DEFAULT,      // 空闲，没有活跃事务
    TRANS_START,        // 事务已开始，但还未分配事务 ID
    TRANS_INPROGRESS,   // 事务正在进行（已分配 XID）
    TRANS_COMMIT,       // 正在提交
    TRANS_ABORT,        // 正在回滚
    TRANS_PREPARE       // 正在准备 2PC
} TransState;
```text

状态转换路径：

### 状态之间的关键边界

TRANS_START 和 TRANS_INPROGRESS 的区别在于是否分配了事务 ID（`XID`）。这个区别直接影响 MVCC 快照——`GetSnapshotData()` 只扫描已经分配了 XID 的事务（`TRANS_INPROGRESS`），处于 `TRANS_START` 的纯读事务不会出现在快照的 `xip[]` 数组中。因此一个执行 `SELECT` 的长事务不会阻止 VACUUM 清理（至少在它还没写任何东西之前）——这是 PG 相比某些数据库的一个重要优化。

### TransactionStateData：单个事务的完整状态

每个事务对应一个 `TransactionStateData` 结构体：

```c
// src/backend/access/transam/xact.c
typedef struct TransactionStateData {
    TransactionId   transactionId;       // 顶层事务 XID
    SubTransactionId subTransactionId;    // 子事务计数器
    char           *name;                 // savepoint 名称（子事务时有效）
    int             savepointLevel;       // savepoint 嵌套深度
    TransState      state;               // 当前状态
    TBlockState     blockState;          // 事务块状态（BEGIN/END 嵌套级别）
    int             nestingLevel;        // 嵌套深度（1 = 顶层）
    int             gucNestLevel;        // GUC 嵌套级别
    MemoryContext    curTransactionContext; // 事务内存上下文
    ResourceOwner    curTransactionOwner;  // 资源追踪器
    TimestampTz      startTimestamp;        // 事务开始时间
    bool             startedInRecovery;     // 是否在 recovery 中开始
    bool             didLogXid;             // 是否已 WAL-log 此 XID
    int              parallelModeLevel;     // 并行模式嵌套级别
} TransactionStateData;

// src/backend/access/transam/xact.c
void DefineSavepoint(const char *name) {
    TransactionState s;

    // 1. 检查同名 savepoint 是否存在
    // 2. 分配新的 TransactionState 并压栈
    s->transactionId = GetCurrentTransactionId();
    s->subTransactionId = currentSubTransactionId++;
    s->name = memory_strdup(name);
    s->savepointLevel = s->nestingLevel;
    s->state = TRANS_INPROGRESS;
    s->blockState = TBLOCK_SUBINPROGRESS;

    // 3. 创建子事务的资源追踪器
    s->curTransactionOwner =
        ResourceOwnerCreate(CurrentResourceOwner, "SubTransaction");

    // 4. 创建子事务的内存上下文
    s->curTransactionContext =
        AllocSetContextCreate(CurrentMemoryContext, ...);

    // 5. 通知各子系统（resource owner、buffer、catcache 等）
    AtSubStart_Notify();
    AfterTriggerBeginSubXact();
}
```text

关键点：每个子事务有独立的 `ResourceOwner` 和 `MemoryContext`。当 `ROLLBACK TO sp` 时，PG 通过销毁子事务的 ResourceOwner 来释放该子事务持有的所有 buffer pin、锁和内存——不需要遍历所有资源逐个释放。

**2. RollbackToSavepoint() — 回滚到 savepoint**

```c
// src/backend/access/transam/xact.c
void RollbackToSavepoint(List *names) {
    // 1. 解析 savepoint 名称，找到对应的 nestingLevel
    // 2. AbortSubTransaction() 逐层回滚子事务
    while (CurrentTransactionState->nestingLevel > targetLevel) {
        AbortSubTransaction();  // 释放 ResourceOwner、MemoryContext
        PopTransaction();       // 弹栈
    }
    // 3. 重新设置为 TRANS_INPROGRESS（不是 TRANS_ABORT）
    CurrentTransactionState->state = TRANS_INPROGRESS;
    CurrentTransactionState->blockState = TBLOCK_SUBINPROGRESS;
}

// src/include/utils/resowner.h
// ResourceOwner 追踪的资源类型
// - buffer pins (ReadBuffer → ReleaseBuffer)
// - catcache / relcache references
// - heavyweight locks (LockAcquire → LockRelease)
// - plan cache references (CachedPlanSource)
// - JIT contexts
// - snapshot references
// - files (OpenTemporaryFile)
```text

当子事务回滚时，`ResourceOwnerRelease()` 遍历子事务的 `ResourceOwner`，释放该子事务独立获取的所有资源。父事务持有的资源（如之前获取的锁）不受影响。这是 savepoint 回滚的工程基础——不需要知道每个资源的具体类型和处理方式，`ResourceOwner` 统一管理。

### 子事务与 XID 分配

子事务也有独立的事务 ID——SubTransactionId。但注意 `SubTransactionId` 不是全局可见的 `TransactionId`。MVCC 可见性判断只看顶层事务的 XID，子事务的 XID 被缓存在 `PGPROC.subxids` 数组中（`PGPROC_MAX_CACHED_SUBXIDS` = 64），并通过 `pg_subtrans` SLRU 目录管理父子关系。

---

## 三、两阶段提交（2PC）：PREPARE TRANSACTION 的持久化

### 为什么需要 2PC

两阶段提交解决的是**跨多个资源管理器**的分布式事务问题。如果两个 PG 数据库需要原子地提交同一个分布式事务，单靠 `COMMIT` 不够——第一个数据库可能成功提交，第二个可能失败，没有回滚机制。2PC 引入一个额外的 `PREPARE` 阶段：所有参与者在真正提交前先确认"我能提交"，只有所有参与者都 PREPARE 成功，协调者才发出 COMMIT。

在 PG 中，2PC 通过 `PREPARE TRANSACTION 'gtrid'` 触发。准备后的事务不依赖原始 Backend 进程——它被持久化到磁盘，即使 PG 重启，准备状态的事务也能被恢复并最终提交或回滚。

### PREPARE 的流程

```c
// src/backend/access/transam/xact.c
void PrepareTransactionBlock(const char *gid) {
    // 1. 获取事务的完整状态
    // 2. 调用 EndPrepare() → 写 WAL 和状态文件
    // 3. 释放 Backend 持有的资源（锁、buffer pin 等）
}

// src/include/access/twophase.h
typedef struct TwoPhaseFileHeader {
    uint32          magic;           // 魔数：TWOPHASE_MAGIC
    uint32          total_len;       // 文件总长度
    TransactionId   xid;             // 事务 XID
    Oid             database;        // 数据库 OID
    Oid             owner;           // 事务的拥有者
    int32           nsubxacts;       // 子事务数量
    bool            initdb;          // 是否在 initdb 中准备
    int16           ncommitrels;     // 提交时需要失效的 relcache 数量
    // 后面跟着：
    // - GID（字符串）
    // - 子事务 XID 数组
    // - 失效消息列表
    // - 锁信息
} TwoPhaseFileHeader;
```text

状态文件包含足够的信息让事务在 PG 重启后恢复。关键内容：

- **锁信息**：PREPARE 后事务不持有锁（为了不阻塞其他事务），但锁信息被写入状态文件。在 PREPARE 和决议之间的窗口期，事务在 `LockManager` 中不持有锁，但锁信息存在状态文件中，需要恢复时才重建。
- **子事务列表**：PREPARE 之前 PG 会先内部提交所有活跃子事务，并将子事务 XID 列表记录在状态文件中。

### PREPARE 后的事务恢复

重启后，`StartupXLOG()` 在 recovery 结束时调用 `PrescanPreparedTransactions()` 和 `RecoverPreparedTransactions()`：

```c
// src/backend/access/transam/twophase.c
void RecoverPreparedTransactions(void) {
    // 扫描 pg_twophase/ 目录
    // 对每个状态文件：
    //   1. 读取 TwoPhaseFileHeader
    //   2. 重新获取锁（从状态文件中读取锁信息）
    //   3. 把事务加入全局 prepared transaction 列表
    //   4. 重建失效消息
}

// src/backend/access/transam/twophase.c
typedef struct GlobalTransactionData {
    TransactionId   xid;           // 事务 XID
    char            gid[GIDSIZE];  // 全局标识符
    int             pgprocno;      // 关联的 PGPROC slot
    LM_LOCK        *lockchain;     // 锁链
    bool            valid;         // 此 slot 是否在使用
    bool            ondisk;        // 状态文件是否已存在
    bool            inredo;        // 是否在 redo 中重建
} GlobalTransactionData;
```text

每个 `max_prepared_transactions` slot 大约占用几百字节，加上锁表的开销。如果你需要 2PC（例如分布式事务协调器），需要在 `postgresql.conf` 中设为实际需求的 2 倍——为并发 PREPARE 留出余量。

---

## 四、事务 ID 分配与 Wraparound 防线

### AssignTransactionId

事务 ID 不是在 `BEGIN` 时分配，而是在第一个**写操作**时才分配。这是 PG 的"懒分配"策略：

```c
// src/backend/access/transam/xact.c
TransactionId GetCurrentTransactionId(void) {
    if (CurrentTransactionState->state == TRANS_DEFAULT)
        elog(ERROR, "GetCurrentTransactionId: not in a transaction");

    if (!TransactionIdIsValid(CurrentTransactionState->transactionId))
        AssignTransactionId();  // 第一次写操作触发

    return CurrentTransactionState->transactionId;
}

// src/backend/access/transam/varsup.c
TransactionId GetNewTransactionId(bool isSubXact) {
    TransactionId xid;

    LWLockAcquire(XidGenLock, LW_EXCLUSIVE);
    xid = ShmemVariableCache->nextXid;
    // 推进 nextXid
    TransactionIdAdvance(ShmemVariableCache->nextXid);

    // 检查 wraparound 危险
    if (ShmemVariableCache->xidVacLimit < xid) {
        // 触发 autovacuum 以冻结旧 XID
        SendPostmasterSignal(PMSIGNAL_START_AUTOVAC_LAUNCHER);
    }
    LWLockRelease(XidGenLock);

    // 把 XID 写入 PGPROC
    if (!isSubXact)
        ProcArrayAdd(MyProc, xid);

    return xid;
}
```text

注意 `XidGenLock`——这是一个全局 LWLock，在高并发插入场景（很多事务同时第一次写入）时，所有 Backend 都排队等这个锁。每个事务只获取一次（在分配 XID 时），不构成常见性能瓶颈，但在极端的单语句短事务场景中值得关注。

### xidStopLimit 和 xidWrapLimit

PG 的 `TransactionId` 是 32-bit 无符号整数，取值范围约 40 亿（$2^{32} - 3$，0 的 `InvalidTransactionId`、1 的 `BootstrapTransactionId`、2 的 `FrozenTransactionId` 为保留值）。40 亿个事务之后，XID 会**回卷（wraparound）**。PG 通过 MVCC 的"XID 比较使用模运算"来使回卷安全——但这依赖一个关键假设：**任何事务 ID 的"年龄"不超过 20 亿**（$2^{31}$）。

如果不冻结旧 tuple 的 `xmin`，回卷会把"旧的数据"误判为"未来的数据"，导致数据静默丢失。PG 设置了三道防线：

```c
// src/backend/access/transam/varsup.c
void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
                            Oid oldest_datoid) {
    // 第一道防线：autovacuum 加速
    xidVacLimit = oldest_datfrozenxid +
        (autovacuum_freeze_max_age -
         autovacuum_freeze_max_age * 0.05);

    // 第二道防线：强制 autovacuum（即使 autovacuum=off）
    xidWarnLimit = oldest_datfrozenxid +
        (autovacuum_freeze_max_age -
         autovacuum_freeze_max_age * 0.025);

    // 第三道防线：拒绝分配新 XID
    xidStopLimit = oldest_datfrozenxid +
        (autovacuum_freeze_max_age -
         autovacuum_freeze_max_age * 0.01);

    // 绝对上限：wraparound 发生点
    xidWrapLimit = oldest_datfrozenxid +
        (autovacuum_freeze_max_age + 1);

    // 将防线写入共享内存
    ShmemVariableCache->xidVacLimit = xidVacLimit;
    ShmemVariableCache->xidWarnLimit = xidWarnLimit;
    ShmemVariableCache->xidStopLimit = xidStopLimit;
    ShmemVariableCache->xidWrapLimit = xidWrapLimit;
}

-- 某个事务被 PREPARE 但从未 COMMIT PREPARED
BEGIN;
INSERT INTO orders VALUES (1, 'pending');
PREPARE TRANSACTION 'order_1';
-- 忘记执行 COMMIT PREPARED 'order_1'
```text

这个 prepared transaction 会：
- 永久占用一个 `max_prepared_transactions` slot
- 恢复后持有它 PREPARE 时持有的所有锁（阻塞对相关表的写入）

排查 SQL：

```sql
-- 查看所有 prepared transaction
SELECT transaction, gid, prepared,
       extract(epoch FROM now() - prepared) AS age_seconds,
       owner, database
FROM pg_prepared_xacts;

-- 如果发现有 age_seconds 超过预期的记录：
-- 1. 先确认事务的来源：owner 和 database
-- 2. 检查分布式事务协调器状态
-- 3. 如果确认已无法正常决议：ROLLBACK PREPARED 'gid'

CREATE OR REPLACE FUNCTION bad_loop() RETURNS void AS $$
DECLARE
    i INTEGER;
BEGIN
    FOR i IN 1..10000 LOOP
        BEGIN
            -- 某些可能失败的操作
            INSERT INTO log VALUES (i);
        EXCEPTION WHEN OTHERS THEN
            -- 忽略错误
        END;
    END LOOP;
END;
$$ LANGUAGE plpgsql;
```text

每次进入 `BEGIN ... EXCEPTION ... END` 块，PG 创建一个子事务。虽然有 64 个缓存的 subxid 限制，但子事务本身（`TransactionState` 栈节点）没有硬限制——它可以无限增长，每次 `AbortSubTransaction()`（异常发生时）也需要清理当前子事务的资源。

更严重的后果是：如果外层事务是一个长事务，深层嵌套的子事务会让 `PGPROC.subxids` 溢出。当子事务超过 64 个时，PG 不再将子 XID 缓存在 `PGPROC` 中，而是每次可见性检查都去查 `pg_subtrans` SLRU——这比查 `PGPROC` 慢得多。

排查方法：

```sql
-- 查看当前活跃查询的事务年龄和子事务数量
SELECT pid, state, xact_start,
       now() - xact_start AS xact_duration,
       substring(query, 1, 80) AS query
FROM pg_stat_activity
WHERE state = 'active'
  AND now() - xact_start > interval '1 minute'
ORDER BY xact_start;

-- Session A: 长查询
BEGIN;
SELECT * FROM huge_table;  -- 可能跑很久
-- 还没写任何东西，状态是 TRANS_START，没有 XID

-- ... 过了很久 ...

-- Session A: 突然写了一条
UPDATE huge_table SET status = 'done' WHERE id = 1;
-- 此时分配 XID，进入 TRANS_INPROGRESS，加入 procArray
-- 这个 XID 的"年龄"会从现在开始计算——之前的等待时间不算

COMMIT;
```text

Session A 在分配 XID 之后仍然在 `procArray` 中，会阻止 VACUUM 清理此后产生的 dead tuple。但因为 XID 分配发生在 UPDATE 执行时（而非事务开始时），`xmin` 快照的年龄比直觉中要年轻——这对 wraparound 计算有利，但对 VACUUM 效率没有实质帮助（VACUUM 关心的是所有活跃 XID 的最小值 `oldest xmin`，不关心它何时开始）。

---

## 六、实验：观察事务状态和 2PC

### 1. 观察读事务没有 XID

```sql
-- Session 1
BEGIN;
SELECT txid_current();
-- 输出：一个数字（如 1000）
-- 注意：txid_current() 本身是一个写函数——它强制分配 XID！
-- 用 pg_current_xact_id() 在 PG 13+ 来避免：
SELECT pg_current_xact_id_if_assigned();
-- 如果是纯读事务，输出：NULL（未分配 XID）

-- 查看自己的 backend 信息
SELECT pid, backend_xid, backend_xmin
FROM pg_stat_activity
WHERE pid = pg_backend_pid();
-- backend_xid：NULL（没有 XID）
-- backend_xmin：可能有值（如果持有快照）

BEGIN;
INSERT INTO t VALUES (1);                 -- XID 分配
SAVEPOINT sp1;
INSERT INTO t VALUES (2);
SAVEPOINT sp2;
INSERT INTO t VALUES (3);

-- 查看当前子事务状态
SELECT txid_current();
-- 输出：顶层事务 XID

-- 回滚到 sp1——sp2 和中间的工作被丢弃
ROLLBACK TO sp1;

-- 继续
INSERT INTO t VALUES (4);
COMMIT;
-- 最终表中：1, 4
```text

用 gdb 观察子事务栈：

```bash
gdb -p $(pgrep -f "postgres: .* testdb")

(gdb) p CurrentTransactionState->nestingLevel
# 输出：2  (在 BEGIN + 1 个 savepoint 时)
(gdb) p CurrentTransactionState->name
# 输出：0x... "sp1"
(gdb) p CurrentTransactionState->curTransactionOwner
# 输出：独立的 ResourceOwner 指针

-- 确保 max_prepared_transactions > 0
SET max_prepared_transactions = 5;

BEGIN;
INSERT INTO t VALUES (10);
PREPARE TRANSACTION 'test_2pc';
```text

准备后查看文件：

```bash
# 状态文件在 pg_twophase/ 下
ls -la $PGDATA/pg_twophase/
# 输出：1 个文件，文件名是 GID 的 hash

# 查看内容（二进制）
xxd $PGDATA/pg_twophase/00000001 | head -5