55P04 — unsafe_new_enum_value_usage

同一事务中使用了尚未提交的新增 enum 值。

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

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

12 13 14 15 16 17 18 19 20

aliases: 未知
class name: Object Not In Prerequisite State
condition name: unsafe_new_enum_value_usage
lang: en
sqlstate: 55P04

版本定义 PG 18

55P04

速览 {#at-a-glance}

55P04 保护“新加入的 enum 值必须先提交再使用”的规则。它发生在 PostgreSQL 找到仍未提交且被标记为不安全的 enum tuple 后，不是标签语法错误。

含义 {#meaning}

固定 enum.c guard 先接受已经标记为 committed 的 tuple，再直接检查 tuple 的事务 ID；如果该值不在 EnumUncommitted() 列表中，也会接受，因为它不可能比所属类型存活更短。只有剩余的未提交新值才会报此码。因此，同一未提交事务中的 ALTER TYPE ... ADD VALUE 与使用新标签可能触发 55P04，已经提交的标签则不会触发这条 guard。

消息 {#messages}

Primary 模板：unsafe use of new value "%s" of enum type %s
Detail：本调用组没有 detail。
Hint：New enum values must be committed before they can be used.

两个 %s 分别是 enum 标签和格式化后的 enum 类型名，只提供诊断信息，不是值格式规则。

诊断 {#diagnosis}

保留 enum 标签、类型名、SQLSTATE、severity 和事务状态，检查该值是否由同一仍未提交的事务刚刚加入，以及失败使用是否是 enum input/cast 或解析为该 enum 的其他表达式。把这个 guard 与无效 enum 标签（22P02）区分开；22P04 是 COPY 文件格式条件，不是这条 enum guard。还要与重复 ADD VALUE 区分。

处理 {#response}

先从 ERROR 恢复事务：执行 ROLLBACK；若 savepoint 的位置合适、能够保留此前的 ADD VALUE，则执行 ROLLBACK TO SAVEPOINT。新增值仍未提交时不能使用。如果完整回滚或回滚到 savepoint 已丢弃 ADD VALUE，就在新事务中重新执行并 COMMIT；若 savepoint 保留了它，也要先提交该事务，再在能看到已提交 catalog 行的事务中使用新标签。autocommit 下修正提交边界后重试输入，不要重复同一未提交流程。

版本 {#versions}

锁定目录从 12.0 记录此条件；固定源码覆盖 PostgreSQL 18.6。目录边界不表示更早不存在私有或未解析实现。

来源 {#sources}

src/backend/utils/adt/enum.c#L68-102

结构化证据记录保存精确 guard 和消息组；未声称有自然运行案例。

比较版本

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

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "55P04 is unsafe_new_enum_value_usage in SQLSTATE Class 55."
}

claims · resolved-paths

{
  "claim_id": "resolved-paths",
  "limits": "Source confirmation is not natural runtime.",
  "method": "Read complete fixed source context.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0"
  ],
  "statement": "The fixed enum tuple commit and EnumUncommitted guards support the stated commit-before-use mechanism and message."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 55P04 from 12.0; that boundary does not prove exact implementation introduction."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "hint_template": "New enum values must be committed before they can be used.",
    "id": "message.0",
    "primary_template": "unsafe use of new value \"%s\" of enum type %s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "55P04"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "unsafe use of new value \" \" of enum type",
      "position": 0,
      "role": "",
      "template": "unsafe use of new value \"%s\" of enum type %s"
    },
    {
      "kind": "hint",
      "literal": "New enum values must be committed before they can be used.",
      "position": 1,
      "role": "",
      "template": "New enum values must be committed before they can be used."
    }
  ]
}

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#L428"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/enum.c",
  "position": 1,
  "sha256": "35c0f1f5376a5c2ef3d7ea52fa26faad84b493b485ed3a9ad5bb5b5eb45928b2",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/enum.c#L68"
}

来源引用

原始手册引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:746a28d1b80c46fde5495338e98da7761a6b4b28687c9c5e41b6a14f698e70b9

正文语言: zh-Hans · english-manuals:746a28d1b80c46fde5495338e98da7761a6b4b28687c9c5e41b6a14f698e70b9