PostgreSQL ERROR 22001 — 值超出列长度

症状

本篇调试指南针对“PostgreSQL ERROR 22001 — 值超出列长度”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。

可观察到的症状包括：

• ERROR: value too long for type character varying(50)（SQLSTATE 22001）
• 短值插入成功，较长值失败
• 迁移更改了列类型，读写随即失败

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

psql -c "INSERT INTO t(v) VALUES (repeat('a', 60))"

消息会给出确切的列类型与限制，指示需放宽多少。

步骤 2

psql -c "\d t"

确认类型可判断是放宽 varchar 还是改用 text。

常见诱因（按出现频率排序）：

• 值超过声明的 varchar(n) 字符长度
• 迁移收窄了列，而现有代码仍写入更长值
• PostgreSQL 不会自动截断，而是拒绝而非静默裁剪

根因

PostgreSQL 对 varchar(n) 与 char(n) 严格强制长度约束，值过长时抛 SQLSTATE 22001。它从不隐式截断，因此修复方式是放宽列或约束输入。

修复

放宽列或改用带显式 CHECK 的 text，在应用中校验输入长度，并在迁移期间与所有写入方协调类型变更。

注意：一律使用无限 text 会失去有用防护；存在业务限制时应加 CHECK 约束。

ALTER TABLE t ALTER COLUMN v TYPE varchar(200);

-- or text with an explicit business limit
ALTER TABLE t ALTER COLUMN v TYPE text;
ALTER TABLE t ADD CONSTRAINT v_len CHECK (char_length(v) <= 200);

-- read-only widening without locking (PG 11+)
ALTER TABLE t ALTER COLUMN v TYPE varchar(200) USING v::varchar(200);

验证

插入此前失败的值并确认成功；验证存储长度等于输入。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。