↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

Wiki / SQLSTATE

22003 — numeric_value_out_of_range

数值超出目标类型范围，如整数溢出。

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

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

8.18.28.38.49.09.19.29.39.49.59.61011121314151617181920
aliases
未知
class name
Data Exception
condition name
numeric_value_out_of_range
lang
en
sqlstate
22003

版本定义 PG 18

22003

速览 {#at-a-glance}

22003 是 numeric_value_out_of_range。固定源码中的数值转换会报告 integer out of range，其他范围检查路径保留各自的操作上下文。

共享案例把 2147483648 cast 为 integer 以捕获范围错误，再把可表示的 2147483647 作为修复值。应分开发送两条 SELECT；第一条预期失败，之后再执行修复表达式。会话和清理由运行器负责，无需建立 schema。

SELECT '2147483648'::integer;
SELECT '2147483647'::integer;

校准实测整数输入 2147483648 被拒绝并报告 value "2147483648" is out of range for type integer；2147483647 成功。PostgreSQL 18.6 使用 pg_strtoint32_safe，REL_10_23 源码路径使用 pg_atoi；运行器的两条自动提交会话均回到 IDLE。

报文 {#messages}

固定整数输入 guard 以 ERROR 严重性报告 primary：value "%s" is out of range for type %s。其他已确认源码路径使用 value overflows numeric format（numeric 阶乘）和 integer out of range（width_bucket 结果转换）。引用的源码组没有独立 DETAIL 或 HINT；本次运行只观察了整数输入模板。

含义 {#meaning}

22003 表示所选操作无法表示某个数值或范围。固定目录成员既用于整数转换，也用于精确 numeric 溢出和子系统检查；代表性消息包括 integer out of range 与 value overflows numeric format。其他源码路径也可能使用该 SQLSTATE 但消息不同，因此不能只凭 SQLSTATE 判断具体类型。

诊断 {#diagnosis}

先看 primary message 和 source object。本次观察只证明 int4 输入转换的边界，不能代表所有 numeric 表达式。整数转换要确认源/目标整数宽度，以及错误发生在输入、赋值、cast、算术还是扩展函数。numeric 要区分声明的 precision/scale、算术溢出和舍入语义，并保留操作数。值可以语法正确，却仍然超出目标范围。

处置 {#response}

在转换前校验范围，并选择符合业务契约的表示：拒绝值、显式缩放，或使用支持的更宽类型。算术要检查中间结果而不只看最终列。若消息指向特定子系统，应修复该子系统。本次固定案例使用自动提交，失败 cast 后会话仍为 IDLE；显式事务中应先回滚整个事务，或回滚到失败表达式前已有的保存点，再重试修正表达式。不要对确定性的范围错误做无条件重试，也不要静默截断金额、标识符或计数器。

版本 {#versions}

锁定目录从 7.4 记录该条件，并在列出的正式快照及 19beta3 中出现；固定源码覆盖为 PostgreSQL 18.6。

相关条件 {#related}

22001 是字符串长度错误，22007 是日期时间格式错误，22008 是日期时间字段/范围越界。

来源 {#sources}

代表性固定路径包括整数输入的 numutils.c#L603-L612、numeric 溢出的 numeric.c#L3765-L3769 和 width_bucket 结果转换的 numeric.c#L2042-L2046。结构化证据记录记录了固定消息族与源码哈希。

比较版本

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

cases · integer_out_of_range
{
  "assertions": [
    "SQLSTATE is 22003",
    "The diagnostic identifies integer range overflow",
    "The failed autocommit session remains IDLE",
    "A representable int4 value succeeds afterward"
  ],
  "case_id": "integer_out_of_range",
  "cleanup": "Drop the case schema with an owner connection.",
  "has_snippet": true,
  "position": 0,
  "preconditions": [],
  "repair": "Use a representable integer or choose a wider numeric type after checking the business range; do not treat a conversion error as a generic data truncation.",
  "trigger": "Cast the decimal text 2147483648 to the target integer type.",
  "versions": [
    "10",
    "18"
  ]
}
claims · identity
{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22003 is numeric_value_out_of_range in SQLSTATE Class 22."
}
claims · mechanism.integer-input
{
  "claim_id": "mechanism.integer-input",
  "limits": "This is the selected runtime path; other integer widths have their own input functions.",
  "method": "Read numutils.c out_of_range branch.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.integer-input"
  ],
  "statement": "The integer input routine reports 22003 when a parsed value exceeds the int32 range, with the value and target type in the primary message."
}
claims · mechanism.numeric-format
{
  "claim_id": "mechanism.numeric-format",
  "limits": "This message is not the same as an integer cast failure.",
  "method": "Read numeric.c overflow guard.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.path.numeric-format"
  ],
  "statement": "The numeric factorial path reports 22003 when the result would overflow the numeric format."
}
claims · mechanism.subsystem
{
  "claim_id": "mechanism.subsystem",
  "limits": "The primary message and source object are required to identify the repair.",
  "method": "Read the complete conversion guard.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.path.width-bucket"
  ],
  "statement": "Other numeric operations such as width_bucket can use a shorter integer-out-of-range message under the same SQLSTATE."
}
claims · history
{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 4,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22003 from 7.4 without proving an exact implementation introduction date."
}
claims · runtime.observation
{
  "claim_id": "runtime.observation",
  "limits": "The observation covers an integer input cast, not the other numeric or subsystem paths.",
  "method": "Execute the shared registry and inspect selected summaries.",
  "position": 5,
  "runtime": [
    "runtime.22003-data1-latest.latest",
    "runtime.22003-data1-pg10.pg10"
  ],
  "sources": [
    "manifest.22003",
    "snippet-registry.22003"
  ],
  "statement": "The integer_out_of_range case passed on isolated PostgreSQL 18.6 and 10.21: casting 2147483648 raised 22003, left the autocommit session IDLE, and 2147483647 succeeded."
}
messages · message.integer
{
  "limits": "",
  "message_id": "message.integer",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.integer",
    "primary_template": "value \"%s\" is out of range for type %s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.integer-input"
    ],
    "sqlstate": "22003"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.integer-input"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "value \" \" is out of range for type",
      "position": 0,
      "role": "",
      "template": "value \"%s\" is out of range for type %s"
    }
  ]
}
messages · message.numeric
{
  "limits": "",
  "message_id": "message.numeric",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.numeric",
    "primary_template": "value overflows numeric format",
    "severity_source": "ERROR",
    "sources": [
      "src.path.numeric-format"
    ],
    "sqlstate": "22003"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.numeric-format"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "value overflows numeric format",
      "position": 0,
      "role": "",
      "template": "value overflows numeric format"
    }
  ]
}
messages · message.width-bucket
{
  "limits": "",
  "message_id": "message.width-bucket",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.width-bucket",
    "primary_template": "integer out of range",
    "severity_source": "ERROR",
    "sources": [
      "src.path.width-bucket"
    ],
    "sqlstate": "22003"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.width-bucket"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "integer out of range",
      "position": 0,
      "role": "",
      "template": "integer out of range"
    }
  ]
}
runtimes · runtime.22003-data1-latest.latest · 18.6 (Homebrew) · passed
{
  "cases": [
    "integer_out_of_range"
  ],
  "limits": "",
  "position": 0,
  "raw": {
    "cases": [
      "integer_out_of_range"
    ],
    "id": "runtime.22003-data1-latest.latest",
    "observed": {
      "sqlstate": "22003",
      "status_after_repair": "IDLE"
    },
    "raw": "verify/results/22003-data1-latest/latest/raw.jsonl",
    "raw_sha256": "175423ac2544f055d99352849c7b595f3a7856597282eca042dec0d301f85bb8",
    "run_id": "22003-data1-latest",
    "server_version": "18.6 (Homebrew)",
    "server_version_num": 180006,
    "snippet_registry": {
      "path": "verify/cases/22003/snippets.json",
      "sha256": "6b32f84593ac976a3a39460cd680f9b64bbfd0c62caf1a32b26a561f38a07f2e"
    },
    "status": "passed",
    "summary": "verify/results/22003-data1-latest/latest/summary.json",
    "summary_sha256": "b75b028698e01f0a8d2e46c2cdc8eeb82e95d9bc57bcdd6a036874de387ab0b7",
    "target": "latest"
  },
  "run_id": "22003-data1-latest",
  "runtime_id": "runtime.22003-data1-latest.latest",
  "server_version": "18.6 (Homebrew)",
  "status": "passed",
  "target": "latest"
}
runtimes · runtime.22003-data1-pg10.pg10 · 10.21 (Debian 10.21-1.pgdg90+1) · passed
{
  "cases": [
    "integer_out_of_range"
  ],
  "limits": "",
  "position": 1,
  "raw": {
    "cases": [
      "integer_out_of_range"
    ],
    "id": "runtime.22003-data1-pg10.pg10",
    "observed": {
      "sqlstate": "22003",
      "status_after_repair": "IDLE"
    },
    "raw": "verify/results/22003-data1-pg10/pg10/raw.jsonl",
    "raw_sha256": "00cd428c715f1b196579c4529a65e93a2e7967941a51c0c3d05cb981669a666e",
    "run_id": "22003-data1-pg10",
    "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
    "server_version_num": 100021,
    "snippet_registry": {
      "path": "verify/cases/22003/snippets.json",
      "sha256": "6b32f84593ac976a3a39460cd680f9b64bbfd0c62caf1a32b26a561f38a07f2e"
    },
    "status": "passed",
    "summary": "verify/results/22003-data1-pg10/pg10/summary.json",
    "summary_sha256": "5ed100d3d0ae588e15638a04477f34541365eaa5832a48b651ad0e3ed7d46a77",
    "target": "pg10"
  },
  "run_id": "22003-data1-pg10",
  "runtime_id": "runtime.22003-data1-pg10.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#L197"
}
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.path.integer-input
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numutils.c",
  "position": 2,
  "sha256": "9018d559d8a2b04f6d3fa8fedeb754fc5f1f8cd8594292e6adc5108e8f97f1bf",
  "source_id": "src.path.integer-input",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numutils.c#L603-L612"
}
sources · src.path.numeric-format
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numeric.c",
  "position": 3,
  "sha256": "6cde7cd60b3330b83be35d1f014045f5fb5fe737f3c5db4c8ed4080b99f2b666",
  "source_id": "src.path.numeric-format",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numeric.c#L3765-L3769"
}
sources · src.path.width-bucket
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numeric.c",
  "position": 4,
  "sha256": "6cde7cd60b3330b83be35d1f014045f5fb5fe737f3c5db4c8ed4080b99f2b666",
  "source_id": "src.path.width-bucket",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numeric.c#L2042-L2046"
}
sources · snippet-registry.22003
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "verify/cases/22003/snippets.json",
  "position": 5,
  "sha256": "6b32f84593ac976a3a39460cd680f9b64bbfd0c62caf1a32b26a561f38a07f2e",
  "source_id": "snippet-registry.22003",
  "tag": "",
  "url": ""
}
sources · manifest.22003
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "verify/cases/22003/cases.json",
  "position": 6,
  "sha256": "f0416c30e704d445f14a0e53c15116980acd185a6ae0589d5320ad53f5caa7db",
  "source_id": "manifest.22003",
  "tag": "workspace",
  "url": "verify/cases/22003/cases.json"
}

来源引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:ce25e643404a9e7ba43be903af6298402faa8fbff985eac2e1b6d049b34b04ec

正文语言: zh-Hans · english-manuals:ce25e643404a9e7ba43be903af6298402faa8fbff985eac2e1b6d049b34b04ec