↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 错误代码 / Class 25 事务状态无效

25P03 idle_in_transaction_session_timeout

事务中空闲会话超时

ERROR 已实测 详解 实测通过

类别
Class 25 事务状态无效
严重等级
ERROR
条件名
idle_in_transaction_session_timeout
宏名称
ERRCODE_IDLE_IN_TRANSACTION_SESSION_TIMEOUT
启用版本
9.6
状态
活跃

版本覆盖

  1. 18
  2. 17
  3. 16
  4. 15
  5. 14
  1. 13
  2. 12
  3. 11
  4. 10
  1. 19 beta
  2. 20 dev

速览

25P03 是终止会话的 FATAL 条件。当会话在开放事务中等待客户端下一条查询的时间超过有效 idle_in_transaction_session_timeout 时触发。选定案例使用 300 ms 作为测试触发值，不是生产建议。

含义

该超时防止会话在等待客户端期间长期持有开放事务，从而持有锁并延迟清理。它作用于事务中的空闲等待，包括 idle in transaction 和 idle in transaction (aborted) 状态，不是正在执行的语句；statement_timeout 取消单条语句，而支持该设置的版本中 transaction_timeout 限制整个事务生命周期。选定运行只覆盖未中止的 INTRANS 路径。

诊断

会话消失前，先在该目标会话自身检查有效的 SHOW idle_in_transaction_session_timeout（或对应的 pg_settings 行）。控制连接上的 SHOW 或 pg_settings 反映的是观察者后端，不能用来确认另一个会话实际通过 SET 得到的值。再从控制连接查看 pg_stat_activity 中 pid、usename、application_name、client_addr、state、xact_start、state_change、query_start、query 等字段，并筛选 state IN ('idle in transaction', 'idle in transaction (aborted)')。若状态已经中止，应把更早的根错误和 25P02 作为独立诊断保留；选定运行是未中止的 INTRANS 路径。这些字段可定位连接池或应用路径以及空闲时长，但观察者权限可能限制可见内容。再按 backend PID、SQLSTATE、error_severity = FATAL 和精确报文关联 FATAL 记录。选定的 psycopg/libpq 栈在驱动诊断和 CSV 日志中都暴露了 25P03；PG18 还提供 JSON 日志。原连接已关闭，不能在其上用 ROLLBACK 修复事务。

处理

把原会话视为已消失：从连接池移除它，重连后再判断能否重试幂等工作。要避免再次发生，应在连接归还连接池前提交或回滚，并修复留下开放事务的应用路径。不要为了压制错误而降低该超时；更短的值会更容易触发终止。可把有效值设在合法空闲时长之上；只有部署明确接受锁和清理风险时才设为 0。服务器关闭该会话时会在退出前回滚开放且尚未完成的事务；死亡连接不能再接收 ROLLBACK。对已终止会话中已知未提交的事务，不能通过该连接恢复。若是另一种网络故障发生在客户端可能已发送 COMMIT 之后，应从新连接对账业务结果再重试；并非每个 25P03 FATAL 都意味着这种不确定性。

可复现案例

在一次性实例上执行过的场景。其中 1 个附有可执行 SQL，正文相应小节里给出。

idle_in_transaction_timeout PG 10 / 18 有 SQL

前置条件

  • A runner-owned disposable target is provisioned.

触发

Set idle_in_transaction_session_timeout, BEGIN, wait idle, and probe the terminated session.

断言

  • The original session is terminated by the timeout
  • The collector records FATAL 25P03 for the matching backend PID
  • A fresh connection can execute SELECT 1

处置

Use the state-specific recovery documented on the page; do not reuse a terminated connection.

清理

Drop the case schema with an owner connection.

FATAL 报文

服务器源码固定报出 terminating connection due to idle-in-transaction timeout，严重级别为 FATAL；原连接会被终止。

报文模板

源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。

主消息 terminating connection due to idle-in-transaction timeout

来源：src/backend/tcop/postgres.c @ REL_18_6

适用范围：This is a static FATAL message; the driver may expose or omit SQLSTATE depending on client stack.

实测诊断

18.6 (Homebrew) / latest：FATAL SQLSTATE 25P03；主报文 terminating connection due to idle-in-transaction timeout；backend PID 26447；原连接已关闭 True；CSV 日志 25P03；JSON 日志 25P03；新连接探测 1。 10.21 (Debian 10.21-1.pgdg90+1) / pg10：FATAL SQLSTATE 25P03；主报文 terminating connection due to idle-in-transaction timeout；backend PID 81；原连接已关闭 True；CSV 日志 25P03；JSON 日志 不适用；新连接探测 1。

代表案例

下列 SQL 片段不是一次性粘贴脚本：在测试连接上执行设置、PID 和 BEGIN 后停止发送查询，由独立观察连接或日志收集器等待 FATAL；原连接终止后，另开新连接执行最后的探测。运行器从共享语句清单（registry）读取这些语句，完整断言、日志收集器关联、环境和清理见 案例导出。

-- set_timeout
SET idle_in_transaction_session_timeout = '300ms';
-- backend_pid
SELECT pg_backend_pid();
-- begin
BEGIN;
-- probe
SELECT 1;

上述片段的 SQLSTATE、诊断、状态和修复断言来自共享语句清单（registry）（SHA-256 95fd079c8bca77c6e3ffc398e404a218e4f810e5fa36e30127cbc6470a6d6eb2）；结构化证据。

作者证据 ID：identity, timeout-path, runtime。选定运行记录：runtime.25P03-batch2c-latest-20260909.latest, runtime.25P03-batch2c-pg10-20260909.pg10。

版本与边界

选定的 300 ms 终止案例在 PostgreSQL 18.6 与 10.21 通过。PG18 按配置提供 CSV 和 JSON 日志记录；PG10 只有 CSV。两个目标的新连接都成功执行 SELECT 1。超时值取决于部署，本案例不规定生产值。

来源

证据

断言

每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。

  • 25P03 is idle_in_transaction_session_timeout in Class 25.

    核实方式Read the fixed condition row and macro.

    不覆盖The code is emitted at session termination severity FATAL in the selected path.

    来源src/backend/utils/errcodes.txt

  • ProcessInterrupts emits FATAL 25P03 after the session has remained idle inside an open transaction longer than idle_in_transaction_session_timeout.

    核实方式Trace the timeout interrupt and the fixed configuration documentation.

    不覆盖The server terminates the connection; ROLLBACK cannot be sent through that dead session.

    来源src/backend/tcop/postgres.c · doc/src/sgml/config.sgml · raw/calls/REL_18_6.jsonl

  • Both selected targets received FATAL 25P03 for the exact backend PID, and a fresh owner connection successfully ran SELECT 1 after termination.

    核实方式Match collector records by PID, SQLSTATE, and message, then probe a fresh connection.

    不覆盖The selected timeout is 300 ms in a runner-owned disposable target; production timeout policy is deployment-specific.

  • The fixed monitoring documentation defines pg_stat_activity as one row per server process with current activity, including xact_start and state_change; pg_settings is defined over pg_show_all_settings for the current backend. Capture timeout settings on the timed session itself, because SHOW or pg_settings on an observer connection cannot establish another backend's effective SET value.

    核实方式Read the fixed monitoring view documentation and system-view definition before writing the observer/session diagnostic split.

    不覆盖Visibility of pg_stat_activity fields depends on observer privileges; the selected runtime records establish PID/log correlation, not universal monitoring permissions.

    来源doc/src/sgml/monitoring.sgml · src/backend/catalog/system_views.sql

  • The fixed monitoring view distinguishes idle in transaction from idle in transaction (aborted); the timeout documentation's open-transaction scope covers idle waiting, while the selected runtime demonstrates only the non-aborted INTRANS path.

    核实方式Read the fixed pg_stat_activity state definitions alongside the timeout GUC description and compare them with the selected runtime status.

    不覆盖No aborted-transaction timeout was run in this batch; preserve any earlier root error and 25P02 separately when diagnosing that state.

    来源doc/src/sgml/monitoring.sgml · doc/src/sgml/config.sgml

  • The fixed protocol documentation states that when the backend closes a connection it rolls back any open incomplete transaction before exiting; the driver cannot send a later ROLLBACK on that closed session.

    核实方式Read the fixed protocol session-termination rule and align the recovery prose with the FATAL path.

    不覆盖This establishes server-side rollback on forced connection close; it does not resolve a separate network failure after a client may have sent COMMIT.

    来源doc/src/sgml/protocol.sgml

运行记录

目标服务器版本结果覆盖案例
latest 18.6 (Homebrew) passed idle_in_transaction_timeout
pg10 10.21 (Debian 10.21-1.pgdg90+1) passed idle_in_transaction_timeout

同类错误代码

Class 25 事务状态无效 下的其他成员。