25001 — 活动 SQL 事务（active_sql_transaction）

命令不能在活动事务块中执行，如 VACUUM。

英文手册覆盖始于 PostgreSQL 8.1. 来源历史与运行验证各自保留独立版本边界。

当前阅读 PG 18·选择有来源记录的版本

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: 未知
class name: Invalid Transaction State
condition name: active_sql_transaction
lang: en
sqlstate: 25001

版本定义 PG 18

25001 — 活动 SQL 事务

速览 {#at-a-glance}

25001 表示当前活动 SQL 事务违反了命令要求的事务边界。本案例在 BEGIN 后执行 VACUUM，得到精确错误；回滚后在事务块外执行 VACUUM 成功且连接保持 IDLE。

含义 {#meaning}

该码覆盖多条路径：PreventInTransactionBlock 会拒绝事务块、子事务或函数中的禁用 utility，源码分别格式化为 %s cannot run inside a transaction block、%s cannot run inside a subtransaction 和 %s cannot be executed from a function。其他路径会拒绝写入后的逻辑复制槽、子事务中的快照导出，或查询开始后的导入快照设置。在已经活动的事务中再次 BEGIN 是独立的 WARNING，因此严重级别和恢复方式取决于具体源码路径。

诊断 {#diagnosis}

记录 SQLSTATE、严重级别、主报文、事务状态和命令。本案例的 VACUUM ERROR 后显式会话进入 INERROR，只有 ROLLBACK 恢复 IDLE。函数或子事务报错时，应先结束该上下文，再把命令作为位于任何显式事务块之外的一条独立顶层 utility 命令发出（例如驱动自动提交的单条命令）；在同一 wrapper 内重试仍不满足 PreventInTransactionBlock。逻辑复制槽和快照报错则要检查是否已有写入、子事务或查询；“事务已在进行中”的 WARNING 不是 VACUUM 的 ERROR，本身不要求回滚。随后选定修复在事务块外执行 VACUUM，并断言成功和 IDLE。

处理 {#response}

禁用 utility 若位于不合适的事务块、函数或子事务中，应移到位于任何显式事务块之外的一条独立顶层命令（通常在自动提交连接上执行）；不要把“顶层”理解为另一个 BEGIN。显式事务中的 ERROR 后先执行 ROLLBACK，再执行该命令。逻辑复制槽必须在此前没有写入的事务中创建；快照导出不能位于子事务，SET TRANSACTION SNAPSHOT 必须早于任何查询。重复 BEGIN 的 WARNING 应保留已有事务，不要仅因警告就回滚。应按精确源码路径处理，不能机械套用 VACUUM 修复。

实测诊断 {#messages}

18.6 (Homebrew) / latest：SQLSTATE 25001；primary VACUUM cannot run inside a transaction block；after_error INERROR；after_rollback IDLE；status_after_vacuum IDLE。 10.21 (Debian 10.21-1.pgdg90+1) / pg10：SQLSTATE 25001；primary VACUUM cannot run inside a transaction block；after_error INERROR；after_rollback IDLE；status_after_vacuum IDLE。

源码报文模板 {#source-templates}

选定的 VACUUM 运行没有覆盖以下源码分支：

ERROR %s cannot run inside a subtransaction（%s 替换为命令名）。
ERROR %s cannot be executed from a function（%s 替换为命令名）。
ERROR cannot create logical replication slot in transaction that has performed writes。
ERROR cannot export a snapshot from a subtransaction。
ERROR SET TRANSACTION SNAPSHOT must be called before any query。
WARNING there is already a transaction in progress。

这些是源码证据，不是本案例新增的运行结论。

代表案例 {#case}

本例中，VACUUM 在显式 BEGIN 块内被拒绝；ROLLBACK 后，同一 utility 作为事务块外的独立命令成功。完整 setup、断言与清理见案例导出：

-- create
CREATE TABLE items(id integer PRIMARY KEY, note text NOT NULL);
-- seed
INSERT INTO items VALUES (1, 'seed');
-- begin
BEGIN;
-- trigger
VACUUM items;
-- rollback
ROLLBACK;
-- followup
SELECT 1 AS usable;
-- repair
VACUUM items;

本案例对应的 SQLSTATE、诊断、事务状态和修复断言均来自经核对的案例 registry；见结构化证据和案例导出。

作者证据 ID：identity, utility-path, other-paths, runtime。选定运行记录：runtime.25001-batch1-latest2-20260909.latest, runtime.25001-batch1-pg10b-20260909.pg10。

版本与边界 {#versions}

锁定目录在 7.4 已观察到该条件，并在列出的正式快照中均存在。选定的 VACUUM 案例在 18.6 与 10.21 通过，包含回滚恢复和事务块外成功修复；其他 25001 路径仅有源码证据。

来源 {#sources}

src.errcodes.18.6 (SHA-256 6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba)
src.calls.REL_18_6 (SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf)
src.xact.18.6 (SHA-256 75b012c0b047d1dc905a30975c244beec366e45eac0dbf109fd21bcd611a8e39)
src.logical.18.6 (SHA-256 3f1bd4c3e627fe78522c4dc9bacf9fa8200e6c82c2d01f7670706eee102b76d1)
src.snapmgr-export.18.6 (SHA-256 b605b69e77a026c143f4cabca079de364b9a8732bfc40f7595be44fb0971ee8)
src.snapmgr-set-snapshot.18.6 (SHA-256 b605b69e77a026c143f4cabca079de364b9a8732bfc40f7595be44fb0971ee8)
doc.vacuum.18.6 (SHA-256 80ca5592cda7b74938385f84f09faac33574374c1a05d605a2d55982e4cf1bbf) · 官方文档

比较版本

SQLSTATE 证据与已记录的运行版本

cases · vacuum_inside_transaction

{
  "assertions": [
    "SQLSTATE is 25001",
    "The transaction enters INERROR and rollback restores IDLE",
    "The same connection can execute a follow-up query",
    "VACUUM succeeds after rollback outside the transaction block"
  ],
  "case_id": "vacuum_inside_transaction",
  "cleanup": "Drop the case schema with an owner connection.",
  "has_snippet": true,
  "position": 0,
  "preconditions": [
    "A disposable table exists",
    "VACUUM is issued after an explicit BEGIN"
  ],
  "repair": "Run transaction-control-restricted utility commands outside the transaction block; rollback the failed transaction before reuse.",
  "trigger": "Run VACUUM inside an explicit transaction block.",
  "versions": [
    "10",
    "18"
  ]
}

claims · identity

{
  "claim_id": "identity",
  "limits": "The code covers several operations that require a transaction boundary, including subtransactions and function execution.",
  "method": "Read the fixed condition row and macro.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "25001 is active_sql_transaction in Class 25."
}

claims · utility-path

{
  "claim_id": "utility-path",
  "limits": "Some commands are allowed inside transactions; inspect the command-specific contract rather than retrying blindly.",
  "method": "Trace PreventInTransactionBlock and the VACUUM transaction restriction.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.xact.18.6",
    "doc.vacuum.18.6",
    "src.calls.REL_18_6"
  ],
  "statement": "A utility such as VACUUM cannot run inside an explicit transaction block; xact.c formats the statement name into the 25001 primary message."
}

claims · other-paths

{
  "claim_id": "other-paths",
  "limits": "Severity and recovery depend on the exact path; do not treat every 25001 as an ERROR.",
  "method": "Read all fixed 25001 report groups selected by the source call scan.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.xact.18.6",
    "src.calls.REL_18_6",
    "src.logical.18.6",
    "src.snapmgr-export.18.6",
    "src.snapmgr-set-snapshot.18.6"
  ],
  "statement": "The same SQLSTATE has distinct source templates for subtransactions, function execution, logical replication slots after writes, and snapshot operations; a WARNING “there is already a transaction in progress” is a separate severity path."
}

claims · runtime

{
  "claim_id": "runtime",
  "limits": "The case covers VACUUM in a transaction, not logical replication slots, snapshot export, function calls, or warning handling.",
  "method": "Read the selected summaries and raw diagnostics.",
  "position": 3,
  "runtime": [],
  "sources": [
    "runtime.25001-batch1-latest2-20260909.latest",
    "runtime.25001-batch1-pg10b-20260909.pg10"
  ],
  "statement": "The selected VACUUM case returned 25001 on PG18.6 and PG10.21, entered INERROR, recovered after ROLLBACK, accepted a follow-up query, and then completed VACUUM outside the transaction block with the connection IDLE."
}

messages · transaction-block

{
  "limits": "The %s substitution is the command name; this is one ERROR path for 25001.",
  "message_id": "transaction-block",
  "path": "",
  "position": 0,
  "raw": {
    "id": "transaction-block",
    "limits": "The %s substitution is the command name; this is one ERROR path for 25001.",
    "primary_template": "%s cannot run inside a transaction block",
    "severity_source": "ERROR",
    "sources": [
      "src.xact.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "ERROR",
  "sources": [
    "src.xact.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "cannot run inside a transaction block",
      "position": 0,
      "role": "",
      "template": "%s cannot run inside a transaction block"
    }
  ]
}

messages · subtransaction

{
  "limits": "The format string is source-backed; substitutions are supplied by the executing path.",
  "message_id": "subtransaction",
  "path": "",
  "position": 1,
  "raw": {
    "id": "subtransaction",
    "limits": "The format string is source-backed; substitutions are supplied by the executing path.",
    "primary_template": "%s cannot run inside a subtransaction",
    "severity_source": "ERROR",
    "sources": [
      "src.xact.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "ERROR",
  "sources": [
    "src.xact.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "cannot run inside a subtransaction",
      "position": 0,
      "role": "",
      "template": "%s cannot run inside a subtransaction"
    }
  ]
}

messages · already-in-progress

{
  "limits": "This source path is explicitly WARNING and must not be presented as the VACUUM ERROR template.",
  "message_id": "already-in-progress",
  "path": "",
  "position": 2,
  "raw": {
    "id": "already-in-progress",
    "limits": "This source path is explicitly WARNING and must not be presented as the VACUUM ERROR template.",
    "primary_template": "there is already a transaction in progress",
    "severity_source": "WARNING",
    "sources": [
      "src.xact.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "WARNING",
  "sources": [
    "src.xact.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "there is already a transaction in progress",
      "position": 0,
      "role": "",
      "template": "there is already a transaction in progress"
    }
  ]
}

messages · function

{
  "limits": "The %s substitution is the command name; this branch is rejected because it is called from a function.",
  "message_id": "function",
  "path": "",
  "position": 3,
  "raw": {
    "id": "function",
    "limits": "The %s substitution is the command name; this branch is rejected because it is called from a function.",
    "primary_template": "%s cannot be executed from a function",
    "severity_source": "ERROR",
    "sources": [
      "src.xact.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "ERROR",
  "sources": [
    "src.xact.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "cannot be executed from a function",
      "position": 0,
      "role": "",
      "template": "%s cannot be executed from a function"
    }
  ]
}

messages · logical-slot-after-write

{
  "limits": "The source condition is a transaction that already has a top-level transaction ID from writes.",
  "message_id": "logical-slot-after-write",
  "path": "",
  "position": 4,
  "raw": {
    "id": "logical-slot-after-write",
    "limits": "The source condition is a transaction that already has a top-level transaction ID from writes.",
    "primary_template": "cannot create logical replication slot in transaction that has performed writes",
    "severity_source": "ERROR",
    "sources": [
      "src.logical.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "ERROR",
  "sources": [
    "src.logical.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "cannot create logical replication slot in transaction that has performed writes",
      "position": 0,
      "role": "",
      "template": "cannot create logical replication slot in transaction that has performed writes"
    }
  ]
}

messages · snapshot-subtransaction

{
  "limits": "The branch rejects export from the current subtransaction; prior committed subtransactions are handled separately by the source.",
  "message_id": "snapshot-subtransaction",
  "path": "",
  "position": 5,
  "raw": {
    "id": "snapshot-subtransaction",
    "limits": "The branch rejects export from the current subtransaction; prior committed subtransactions are handled separately by the source.",
    "primary_template": "cannot export a snapshot from a subtransaction",
    "severity_source": "ERROR",
    "sources": [
      "src.snapmgr-export.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "ERROR",
  "sources": [
    "src.snapmgr-export.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "cannot export a snapshot from a subtransaction",
      "position": 0,
      "role": "",
      "template": "cannot export a snapshot from a subtransaction"
    }
  ]
}

messages · snapshot-after-query

{
  "limits": "The command must be at the top level of a fresh transaction before a query establishes the snapshot.",
  "message_id": "snapshot-after-query",
  "path": "",
  "position": 6,
  "raw": {
    "id": "snapshot-after-query",
    "limits": "The command must be at the top level of a fresh transaction before a query establishes the snapshot.",
    "primary_template": "SET TRANSACTION SNAPSHOT must be called before any query",
    "severity_source": "ERROR",
    "sources": [
      "src.snapmgr-set-snapshot.18.6"
    ],
    "sqlstate": "25001"
  },
  "severity": "ERROR",
  "sources": [
    "src.snapmgr-set-snapshot.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "SET TRANSACTION SNAPSHOT must be called before any query",
      "position": 0,
      "role": "",
      "template": "SET TRANSACTION SNAPSHOT must be called before any query"
    }
  ]
}

runtimes · runtime.25001-batch1-latest2-20260909.latest · 18.6 (Homebrew) · passed

{
  "cases": [
    "vacuum_inside_transaction"
  ],
  "limits": "",
  "position": 0,
  "raw": {
    "case_manifest": {
      "path": "verify/cases/25001/cases.json",
      "sha256": "2a5fad757733e23fd68df23270c4b0dfe108ff9ba0e1ab33c4a69e85c46c7ce1"
    },
    "cases": [
      "vacuum_inside_transaction"
    ],
    "id": "runtime.25001-batch1-latest2-20260909.latest",
    "observed": {
      "after_error": "INERROR",
      "after_rollback": "IDLE",
      "primary": "VACUUM cannot run inside a transaction block",
      "sqlstate": "25001",
      "status_after_vacuum": "IDLE",
      "usable": 1,
      "vacuum_outside_transaction": true
    },
    "raw": "verify/results/25001-batch1-latest2-20260909/latest/raw.jsonl",
    "raw_sha256": "0b164ca0eab22ccc7ad5d18ed6201072049d2b7ba49e8cc99ba65aae172e1ec0",
    "run_id": "25001-batch1-latest2-20260909",
    "server_version": "18.6 (Homebrew)",
    "server_version_num": 180006,
    "snippet_registry": {
      "path": "verify/cases/25001/snippets.json",
      "sha256": "0fc4277a4e2f59e78e54a1fed1ec0efef6bd0d3bd97180e03df596677e847f03"
    },
    "status": "passed",
    "summary": "verify/results/25001-batch1-latest2-20260909/latest/summary.json",
    "summary_sha256": "544bd0ec303a15036fe848468ed90f2674d5c2212e520bf6be2413bfdc91f200",
    "target": "latest"
  },
  "run_id": "25001-batch1-latest2-20260909",
  "runtime_id": "runtime.25001-batch1-latest2-20260909.latest",
  "server_version": "18.6 (Homebrew)",
  "status": "passed",
  "target": "latest"
}

runtimes · runtime.25001-batch1-pg10b-20260909.pg10 · 10.21 (Debian 10.21-1.pgdg90+1) · passed

{
  "cases": [
    "vacuum_inside_transaction"
  ],
  "limits": "",
  "position": 1,
  "raw": {
    "case_manifest": {
      "path": "verify/cases/25001/cases.json",
      "sha256": "2a5fad757733e23fd68df23270c4b0dfe108ff9ba0e1ab33c4a69e85c46c7ce1"
    },
    "cases": [
      "vacuum_inside_transaction"
    ],
    "id": "runtime.25001-batch1-pg10b-20260909.pg10",
    "observed": {
      "after_error": "INERROR",
      "after_rollback": "IDLE",
      "primary": "VACUUM cannot run inside a transaction block",
      "sqlstate": "25001",
      "status_after_vacuum": "IDLE",
      "usable": 1,
      "vacuum_outside_transaction": true
    },
    "raw": "verify/results/25001-batch1-pg10b-20260909/pg10/raw.jsonl",
    "raw_sha256": "1efa43a93beca206fe048de038e4538694746fece446eb129a81fb8e36aa2740",
    "run_id": "25001-batch1-pg10b-20260909",
    "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
    "server_version_num": 100021,
    "snippet_registry": {
      "path": "verify/cases/25001/snippets.json",
      "sha256": "0fc4277a4e2f59e78e54a1fed1ec0efef6bd0d3bd97180e03df596677e847f03"
    },
    "status": "passed",
    "summary": "verify/results/25001-batch1-pg10b-20260909/pg10/summary.json",
    "summary_sha256": "498a7229697ff6f46b6bbb135c3f79215cbb5442e9ce2400f651bb5efb91b151",
    "target": "pg10"
  },
  "run_id": "25001-batch1-pg10b-20260909",
  "runtime_id": "runtime.25001-batch1-pg10b-20260909.pg10",
  "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
  "status": "passed",
  "target": "pg10"
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt"
}

sources · src.calls.REL_18_6

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "raw/calls/REL_18_6.jsonl",
  "position": 1,
  "sha256": "9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf",
  "source_id": "src.calls.REL_18_6",
  "tag": "",
  "url": ""
}

sources · src.xact.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/access/transam/xact.c",
  "position": 2,
  "sha256": "75b012c0b047d1dc905a30975c244beec366e45eac0dbf109fd21bcd611a8e39",
  "source_id": "src.xact.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/access/transam/xact.c#L3654-L3677"
}

sources · doc.vacuum.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "https://www.postgresql.org/docs/18/sql-vacuum.html",
  "kind": "upstream_source",
  "location": "",
  "path": "doc/src/sgml/ref/vacuum.sgml",
  "position": 3,
  "sha256": "80ca5592cda7b74938385f84f09faac33574374c1a05d605a2d55982e4cf1bbf",
  "source_id": "doc.vacuum.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/doc/src/sgml/ref/vacuum.sgml"
}

sources · src.logical.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/replication/logical/logical.c",
  "position": 4,
  "sha256": "3f1bd4c3e627fe78522c4dc9bacf9fa8200e6c82c2d01f7670706eee102b76d1",
  "source_id": "src.logical.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/replication/logical/logical.c#L444-L446"
}

sources · src.snapmgr-export.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/time/snapmgr.c",
  "position": 5,
  "sha256": "b605b69e77a026c143f4cabca079de364b9a8732bfc40f7595be44fb0971ee8",
  "source_id": "src.snapmgr-export.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/time/snapmgr.c#L1152-L1154"
}

sources · src.snapmgr-set-snapshot.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/time/snapmgr.c",
  "position": 6,
  "sha256": "b605b69e77a026c143f4cabca079de364b9a8732bfc40f7595be44fb0971ee8",
  "source_id": "src.snapmgr-set-snapshot.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/time/snapmgr.c#L1409-L1411"
}

来源引用

原始手册引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:3d854acb6b32084a7a74bdad3093c4e30fa1c82d986ac74170fe99968f415652

正文语言: zh-Hans · english-manuals:3d854acb6b32084a7a74bdad3093c4e30fa1c82d986ac74170fe99968f415652