22003 numeric_value_out_of_range

速览

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

含义

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

诊断

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

处置

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

版本

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

相关条件

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

来源

• 上游源码 src/backend/utils/errcodes.txt 第 197 行 REL_18_6 724edf9bd 6e8de346
• 上游源码 src/backend/utils/adt/numutils.c 第 603–612 行 REL_18_6 724edf9bd 9018d559
• 上游源码 src/backend/utils/adt/numeric.c 第 3765–3769 行 REL_18_6 724edf9bd 6cde7cd6
• 上游源码 src/backend/utils/adt/numeric.c 第 2042–2046 行 REL_18_6 724edf9bd 6cde7cd6
• 核验材料 verify/cases/22003/snippets.json 6b32f845
• 核验材料 raw/calls/REL_18_6.jsonl 9ee8a0e8