25P03 — 事务中空闲会话超时（idle_in_transaction_session_timeout）

速览

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 都意味着这种不确定性。

FATAL 报文

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

实测诊断

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。超时值取决于部署，本案例不规定生产值。

相关

25P04 事务超时、25006 只读 SQL 事务、57014 查询取消。

来源

• src.errcodes.18.6 (SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba)
• src.calls.REL_18_6 — raw/calls/REL_18_6.jsonl (SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf)
• src.postgres.18.6 (SHA-256 9fb62275b1badf94d01ab351337b60410cd9b3ab1fe63fa9f23d6d2185a21061)
• src.config.18.6 (SHA-256 ffca322c15315ba670733d6b320f23cbba7374db0d18937298ffc07b58799ef6) · official documentation
• doc.monitoring.18.6 (SHA-256 06b147f8d966fe46821871703ffcee8a3449cc3f7de5b64b9177f48569fe96f6) · 官方监控文档
• src.system_views.18.6 (SHA-256 418f4ae7472fe0742e6fbdc7a055581602c5131e082aa6f17e2c7269bf711972) · 官方 pg_settings 文档
• doc.protocol.18.6 (SHA-256 745339e07ebbc2bb67d98b258e25772ada644ef26011e3cd6b3fcbb435235f89) · 官方协议文档