PostgreSQL / 技术文章

PostgreSQL 序列化失败(40001)应该怎么重试

线上出现事务回滚、SQLSTATE 40001 或高并发写冲突时,真正的问题不是“把失败 SQL 再执行一次”,而是如何在不重复扣款、不发送两次消息、也不把延迟拖垮的前提下重跑完整事务。下面面向应用工程师给出一套可直接落地的错误分类、事务重试模板、退避预算和线上验收方法,最终得到一个可观测、可限流、可证明安全的重试边界。

先确认:40001 代表整笔事务需要重来

PostgreSQL 在 REPEATABLE READ 和 SERIALIZABLE 下都可能用 40001(serialization_failure)主动终止事务,以避免并发执行产生不可接受的序列化结果;错误消息文本可能不同,但 SQLSTATE 是稳定的判断依据。PostgreSQL 18 文档明确要求应用为这类失败准备事务级重试。:contentReference[oaicite:0]{index=0}

因此不要解析 could not serialize access 之类的错误字符串,也不要只重跑最后一条 UPDATE。正确边界是:本次尝试失败后结束当前事务,从新的 BEGIN 开始重新读取、重新计算、重新写入,再次尝试提交。

sql
BEGIN ISOLATION LEVEL SERIALIZABLE;

SELECT stock
FROM inventory
WHERE sku = 'sku-42';

UPDATE inventory
SET stock = stock - 1
WHERE sku = 'sku-42'
  AND stock >= 1;

COMMIT;

如果并发冲突让这次尝试返回 40001,上面从 BEGIN 到 COMMIT 的整个单元都必须作废。下一次尝试不能沿用第一次读到的 stock,因为新事务应基于新的数据库状态重新做业务判断。

先分错误,再决定是否自动重试

PostgreSQL 把 40001 归为 serialization_failure,把 40P01 归为 deadlock_detected;官方文档也指出死锁失败通常值得按完整事务重试。对于 23505 唯一约束冲突和 23P01 排斥约束冲突,只有在应用通过“先读再选择新键”等并发模式生成值时才可能适合重试,不能把所有约束错误统一吞掉后重跑。:contentReference[oaicite:1]{index=1}

SQLSTATE 默认策略 原因
40001 重试完整事务 PostgreSQL 已主动回滚本次序列化尝试
40P01 通常重试完整事务 死锁检测会终止其中一个事务
23505 / 23P01 仅按明确业务模式重试 很多时候它们代表真实输入冲突,不是瞬时故障
57014 不默认自动重试 可能来自查询取消或超时,立即重试可能放大过载
08xxx 不按 40001 处理 连接中断可能让提交结果未知,应先做幂等或结果核对

尤其要区分“确定回滚”和“提交结果未知”。40001 明确告诉你这次事务没有成功提交;但如果客户端在 COMMIT 附近断线,应用未必知道服务器最终是否提交。后者不能靠普通重试循环解决,需要稳定的 operation key、幂等写入或事后查询来消除重复执行风险。

把重试循环放在事务外层

一个可靠实现至少要满足四点:每次尝试重新获取事务上下文;失败后先结束当前事务;只对白名单 SQLSTATE 重试;等待期间不要占着数据库连接。下面用 TypeScript 和 pg 展示一个完整模板,其他语言可以按同样边界实现。

typescript
import { Pool, PoolClient } from "pg";

type PgError = Error & { code?: string };

const RETRYABLE = new Set(["40001", "40P01"]);

const sleep = (ms: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, ms));

export async function withRetryingTransaction<T>(
  pool: Pool,
  work: (client: PoolClient) => Promise<T>,
  maxAttempts = 5,
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const client = await pool.connect();
    let shouldRetry = false;

    try {
      await client.query("BEGIN ISOLATION LEVEL SERIALIZABLE");

      const result = await work(client);

      await client.query("COMMIT");
      return result;
    } catch (error) {
      await client.query("ROLLBACK").catch(() => undefined);

      const code = (error as PgError).code;
      const retryable = code !== undefined && RETRYABLE.has(code);

      if (!retryable || attempt === maxAttempts) {
        throw error;
      }

      shouldRetry = true;
    } finally {
      client.release();
    }

    if (shouldRetry) {
      const baseDelayMs = 25;
      const capDelayMs = 400;
      const windowMs = Math.min(
        capDelayMs,
        baseDelayMs * 2 ** (attempt - 1),
      );
      const delayMs = Math.floor(Math.random() * windowMs);
      await sleep(delayMs);
    }
  }

  throw new Error("unreachable");
}

这个模板的关键不是 maxAttempts = 5 或 25 ms 这些示例值,而是结构:work 每次都在新事务中执行;COMMIT 失败同样会进入错误分类;连接会在退避前释放;超过预算后把原始错误抛回上层,不会无限循环。

业务代码只把数据库内的可重放逻辑放进 work:

typescript
async function reserveOne(pool: Pool, sku: string): Promise<number> {
  return withRetryingTransaction(pool, async (client) => {
    const result = await client.query<{ stock: number }>(
      "SELECT stock FROM inventory WHERE sku = $1",
      [sku],
    );

    if (result.rowCount !== 1 || result.rows[0].stock < 1) {
      throw new Error("out_of_stock");
    }

    const nextStock = result.rows[0].stock - 1;

    await client.query(
      "UPDATE inventory SET stock = $2 WHERE sku = $1",
      [sku, nextStock],
    );

    return nextStock;
  });
}

如果第一次尝试读到 stock=1,但随后因并发写入触发 40001,第二次尝试会重新执行 SELECT;它不会拿第一次的 nextStock 继续写。这正是“完整事务重试”与“失败语句重跑”的根本区别。

用退避、抖动和总预算避免重试风暴

没有退避时,一批同时失败的请求会立刻再次撞到同一热点,形成同步重试风暴。更稳妥的做法是指数扩大等待窗口,并在窗口内加入随机抖动,例如第 attempt 次失败后的上限采用 min(cap, base * 2^(attempt-1)),实际等待时间再从 0 到该上限随机选择。

重试次数不能单独决定,应该受请求总时限约束。假设 API 只剩 120 ms,就不该因为“还有三次机会”继续睡眠和重跑;相反,应在每次重试前检查剩余 deadline,把数据库执行、退避和下游处理全部算进同一个预算。高峰期还可以对重试并发做限流,避免失败请求反过来把连接池和热点行压得更重。

建议日志至少记录 sqlstate、attempt、delay_ms、事务类型和总耗时,但不要把完整 SQL 参数、账户信息或其他敏感字段直接写入日志。这样才能区分“偶发冲突被吸收”和“重试正在掩盖持续热点”。

事务内不要直接执行不可回滚的副作用

最危险的写法,是在可重试事务里先调用支付、发邮件、发消息,再执行 COMMIT。如果外部调用已经成功,而数据库事务随后返回 40001,下一次重试会再次执行外部调用,数据库虽然保持一致,业务副作用却重复了。

更安全的模式有两种:把外部动作放到事务成功提交之后,并要求调用端支持稳定幂等键;或者在数据库事务内只写业务数据和 Outbox 事件,让独立 worker 在提交后发送外部消息。Outbox 记录本身也应有稳定的 operation key,防止同一业务请求在多次尝试中生成多条逻辑重复事件。

sql
INSERT INTO outbox (operation_key, event_type, payload)
VALUES ($1, $2, $3)
ON CONFLICT (operation_key) DO NOTHING;

这里的 operation_key 必须由同一次业务操作稳定地产生,而不是每次事务重试都生成新 UUID。这样即使应用遇到连接中断、超时或进程重启,也有办法查询“这笔操作是否已经被接受”,而不是把所有不确定状态都当成 40001 再执行一次。

上线前验证重试真的安全

重试逻辑上线后,不应只看“接口错误率下降”。至少同时观察 40001/40P01 发生率、每笔事务尝试次数、重试耗时、最终耗尽次数、连接池等待和核心业务不变量。持续升高的重试率通常说明热点、事务过长、访问顺序或数据模型仍有竞争问题;重试是正确性保险丝,不是提高吞吐量的替代方案。

压测时可以先把 maxAttempts 暂时设为 1,测出未被重试隐藏的原始冲突率;再启用正式预算,确认最终成功率提高的同时,P95/P99 延迟、数据库 CPU、锁等待和连接池没有失控。对关键路径还应加入并发回归测试,明确验证“成功提交一次、外部副作用至多一次、失败耗尽后错误可见”。

线上判断可以收敛成一句规则:收到 40001 或明确允许重试的 40P01 时,从事务入口开始重跑;遇到约束错误先判断业务语义;遇到连接类未知提交状态先做幂等核对;任何重试都必须受总时限、尝试次数和副作用边界约束。

目录与阅读设置

记录一个想法

PostgreSQL 序列化失败(40001)应该怎么重试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通