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

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

百科 / 错误代码 / Class 22 数据异常

22003 numeric_value_out_of_range

ERROR 已实测 详解 实测通过

类别
Class 22 数据异常
严重等级
ERROR
条件名
numeric_value_out_of_range
宏名称
ERRCODE_NUMERIC_VALUE_OUT_OF_RANGE
启用版本
7.4
状态
活跃

版本覆盖

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

速览

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。

报文

固定整数输入 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；本次运行只观察了整数输入模板。

报文模板

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

主消息 value "%s" is out of range for type %s

来源：src/backend/utils/adt/numutils.c @ REL_18_6

主消息 value overflows numeric format

来源：src/backend/utils/adt/numeric.c @ REL_18_6

主消息 integer out of range

来源：src/backend/utils/adt/numeric.c @ REL_18_6

含义

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

诊断

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

处置

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

可复现案例

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

integer_out_of_range PG 10 / 18 有 SQL

触发

Cast the decimal text 2147483648 to the target integer type.

断言

  • SQLSTATE is 22003
  • The diagnostic identifies integer range overflow
  • The failed autocommit session remains IDLE
  • A representable int4 value succeeds afterward

处置

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.

清理

Drop the case schema with an owner connection.

版本

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

来源

证据

断言

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

  • 22003 is numeric_value_out_of_range in SQLSTATE Class 22.

    核实方式Read fixed definition.

    来源src/backend/utils/errcodes.txt

  • The integer input routine reports 22003 when a parsed value exceeds the int32 range, with the value and target type in the primary message.

    核实方式Read numutils.c out_of_range branch.

    不覆盖This is the selected runtime path; other integer widths have their own input functions.

    来源src/backend/utils/adt/numutils.c

  • The numeric factorial path reports 22003 when the result would overflow the numeric format.

    核实方式Read numeric.c overflow guard.

    不覆盖This message is not the same as an integer cast failure.

    来源src/backend/utils/adt/numeric.c

  • Other numeric operations such as width_bucket can use a shorter integer-out-of-range message under the same SQLSTATE.

    核实方式Read the complete conversion guard.

    不覆盖The primary message and source object are required to identify the repair.

    来源src/backend/utils/adt/numeric.c

  • The locked catalogue records 22003 from 7.4 without proving an exact implementation introduction date.

    核实方式Use catalogue boundary.

    来源src/backend/utils/errcodes.txt

  • 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.

    核实方式Execute the shared registry and inspect selected summaries.

    不覆盖The observation covers an integer input cast, not the other numeric or subsystem paths.

    来源verify/cases/22003/snippets.json

运行记录

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

同类错误代码

Class 22 数据异常 下的其他成员。