更新时间:2026-11-20 GMT+08:00

PREPARE TRANSACTION

功能描述

在分布式数据库中,当一个事务涉及多个节点或多个数据源时,需要通过两阶段提交(Two-Phase Commit, 2PC)协议来保证所有参与者要么全部提交、要么全部回滚。PREPARE TRANSACTION命令用于完成两阶段提交的第一阶段——将当前事务的状态持久化到磁盘上,使其进入“预备”状态。

执行该命令后,事务不再与当前会话关联,其状态完全保存在磁盘上。即使在此后、正式提交请求之前数据库发生崩溃,该预备事务在数据库恢复后仍具有极高的提交成功率。

一旦事务进入预备状态,可以在稍后通过COMMIT PREPARED或ROLLBACK PREPARED命令分别进行提交或回滚。这两条命令可以从任意会话中发出,不限于最初执行事务的会话。

典型使用场景:

  • 跨节点分布式事务:事务涉及多个数据库节点,需要协调者先通知各参与者进入预备状态,再统一决定提交或回滚。
  • 跨系统数据一致性:事务涉及数据库与外部系统(如消息队列、缓存)的协同操作,外部系统确认准备就绪后,再通过COMMIT PREPARED完成最终提交。
  • 故障恢复处理:两阶段提交过程中协调者发生故障,参与者已进入预备状态并持有资源,等待协调者恢复后发出提交或回滚指令。

从发出PREPARE TRANSACTION命令的会话角度来看,该命令执行后当前事务即结束,不再有活跃的当前事务,且预备事务的数据变更效果在该会话中不可见(效果将在事务最终提交时重新可见)。

如果PREPARE TRANSACTION因某些原因执行失败,则当前事务会被自动回滚取消。

注意事项

  • PREPARE TRANSACTION通常由分布式事务协调器自动调用,一般用户不应在应用中显式使用此命令,此语法仅为参考。
  • 该功能仅在维护模式(GUC参数xc_maintenance_mode为on时)下可用。该模式谨慎打开,一般供维护人员排查问题使用,一般用户不应使用该模式。
  • 在运行PREPARE TRANSACTION命令时,必须在postgresql.conf配置文件中增大max_prepared_transactions的数值。建议至少将其设置为等于max_connections,这样每个会话都可以有一个等待中的预备事务。

语法格式

1
PREPARE TRANSACTION transaction_id;

参数说明

表1 PREPARE TRANSACTION参数说明

参数

描述

取值范围

transaction_id

待提交事务的标识符,用于后面在COMMIT PREPARED或ROLLBACK PREPARED时标识这个事务。该标识符即为全局事务ID(GID)。

字符串类型,长度必须小于200字节。不能与当前其他预备事务已使用的标识符同名。示例值:'txn_transfer_001'。

示例

以下示例以银行转账业务为背景,演示PREPARE TRANSACTION的语法用法和预备事务的验证方法。

在DWS分布式环境下,PREPARE TRANSACTION由内部分布式事务协调器自动调用,不支持通过客户端手动执行。以下示例中的PREPARE TRANSACTION步骤为语法说明,实际环境中预备事务由数据库内部自动创建。如需查看和终结内部创建的预备事务,请参见COMMIT PREPARED和ROLLBACK PREPARED。

  1. (可选)清理残留的同名预备事务。如果之前执行过相同GID的PREPARE TRANSACTION但未COMMIT或ROLLBACK,需先清理。

    1
    2
    3
    4
    SET xc_maintenance_mode = on;
    SELECT transaction, gid FROM pg_prepared_xacts WHERE gid = 'txn_transfer_001';
    -- 如果存在残留记录,执行以下命令清理:
    ROLLBACK PREPARED 'txn_transfer_001';
    

  2. 创建测试表并插入初始数据。

    1
    2
    3
    4
    5
    6
    7
    8
    DROP TABLE IF EXISTS accounts;
    CREATE TABLE accounts (
        id      INT PRIMARY KEY,
        name    VARCHAR(50),
        balance NUMERIC(10,2)
    );
    INSERT INTO accounts VALUES (1, 'Alice', 1000.00);
    INSERT INTO accounts VALUES (2, 'Bob', 500.00);
    

  3. 开启事务,执行转账操作:Alice向Bob转账200元。

    1
    2
    3
    BEGIN;
    UPDATE accounts SET balance = balance - 200.00 WHERE id = 1;
    UPDATE accounts SET balance = balance + 200.00 WHERE id = 2;
    

  4. 执行PREPARE TRANSACTION,将当前事务置为预备状态,并指定全局事务标识符为’txn_transfer_001’。(仅为参考,客户端无法执行)

    1
    PREPARE TRANSACTION 'txn_transfer_001';
    

    执行成功后,当前会话不再有活跃事务。

  5. 验证事务已进入预备状态。通过查询pg_prepared_xacts系统视图,确认预备事务已创建,并获取其事务标识符(gid字段值)。

    1
    SELECT transaction, gid, prepared, owner, database FROM pg_prepared_xacts;
    

    预期输出:

    1
    2
    3
    4
    transaction |       gid        |        prepared         |  owner   | database
    ------------+------------------+------------------------+----------+----------
         1234567 | txn_transfer_001 | 2024-01-15 14:30:00+08 | app_user | db_test
    (1 row)
    

    其中gid字段的值txn_transfer_001即为后续执行COMMIT PREPARED或ROLLBACK PREPARED时需要指定的transaction_id。

  6. 确认预备事务的数据变更在当前会话中不可见(因为事务尚未提交)。

    1
    SELECT * FROM accounts ORDER BY id;
    

    预期输出:

    1
    2
    3
    4
    5
    id | name  | balance
    ----+-------+---------
      1 | Alice | 1000.00
      2 | Bob   |  500.00
    (2 rows)
    

    后续操作请参见COMMIT PREPARED(提交预备事务)或ROLLBACK PREPARED(回滚预备事务)

常见问题

Q:如何查询当前存在的预备事务?

A:可以通过查询系统视图pg_prepared_xacts查看当前所有处于预备状态的事务:

1
SELECT transaction, gid, prepared, owner, database FROM pg_prepared_xacts;

其中gid字段的值即为各预备事务的标识符,用于后续COMMIT PREPARED或ROLLBACK PREPARED操作。