Chris van Eijk：PostgreSQL 中“invalid input syntax for type uuid”错误实测
内容提要
PostgreSQL 的“invalid input syntax for type uuid”错误（SQLSTATE 22P02）表示传入文本无法转换为 uuid。PostgreSQL 接受大写、花括号、无连字符等格式，但拒绝空串、undefined、带空格或换行等。该错误多源于应用把缺失值变成字符串，而非数据库本身；行级安全策略中 current_setting 在设置被清空后返回空串也会触发。可用 nullif 或 pg_input_is_valid 安全转换，并应在查询前校验客户端输入。
延伸解读
错误信息中的引号内容才是排查起点
报错里引号内的文本就是 PostgreSQL 实际收到的值，比错误码更有诊断价值。空串、undefined、带空格或换行，分别指向不同的来源：应用把缺失值转成了字符串、JSON null 经 text 转换、或输入未修剪。先看引号内容，再回溯该值在应用层的生成路径，比直接改 SQL 更有效。
连接池让行级安全策略从正常变为报错
current_setting 在会话从未设置过该参数时返回 NULL，一旦设置过（包括 SET LOCAL 提交后、RESET 后），就返回空串。连接池复用的正是“见过该设置”的会话，于是同一查询从返回 0 行变成抛出 22P02。用 nullif 包裹可消除空串，但应用写入 'undefined' 时仍需在 set_config 前校验。
把 uuid 列转成 text 比较会失去索引
where id::text = 'undefined' 虽不报错，却让主键索引失效，在 10 万行表上全表扫描。正确做法是修正传入值，而不是改变比较方式。若值可能非法，可用 pg_input_is_valid 先判断，或 nullif 处理空串，保持 uuid 类型比较以利用索引。
区分客户端输入与内部值：校验策略不同
来自客户端的 id 应在查询前拒绝缺失或格式错误的值，返回 400 或 404；来自自身代码的会话、令牌或设置值，报错说明是 bug 而非待校验输入。PostgreSQL 17 没有 try_cast，可用 pg_input_is_valid 或捕获异常的函数安全转换，导入时还能用 pg_input_error_info 列出坏行而不中断。
Q&A
PostgreSQL 报错 invalid input syntax for type uuid 是什么意思？
该错误（SQLSTATE 22P02）表示 PostgreSQL 试图将一段文本转换为 uuid 类型，但无法转换。错误信息中引号内的部分就是它收到的原始文本，通常能提示值的来源。
PostgreSQL 接受哪些格式的字符串作为 uuid？
除了标准的小写带连字符格式，PostgreSQL 还接受大写、花括号包裹、32 位无连字符、每 4 位后加连字符等格式，转换后统一为小写带连字符形式。但空串、undefined、带空格或换行、带 urn:uuid: 前缀等会被拒绝。
为什么 node-postgres 会发送 'undefined' 字符串导致 uuid 错误？
node-postgres 将 JavaScript 的 null 和 undefined 作为 SQL NULL 发送，不会报错。但若应用将缺失值转成字符串（如 'undefined'、String(null)、空串），再作为参数传入 uuid 列，就会触发该错误。错误在语句解析阶段发生，与表中是否有数据无关。
行级安全策略中使用 current_setting 为什么会引发 uuid 错误？
当策略写成 tenant_id = current_setting('app.tenant', true)::uuid 时，如果会话中该设置从未设置过，current_setting 返回 NULL，不报错；但一旦设置被清空（如 SET LOCAL 提交后、RESET 后），current_setting 返回空串，转换为 uuid 时就会报 invalid input syntax for type uuid: ""。使用 nullif(current_setting('app.tenant', true), '')::uuid 可以避免空串错误。
如何安全地将可能不是 uuid 的字符串转换为 uuid？
PostgreSQL 17 没有 try_cast。可以使用 nullif(x, '')::uuid 处理空串；用 CASE WHEN pg_input_is_valid(x, 'uuid') THEN x::uuid END 安全转换（pg_input_is_valid 自 PostgreSQL 16 起可用）；或使用 PL/pgSQL 函数捕获异常返回 NULL。对于策略中的空串，nullif 足够；但若应用可能写入 'undefined'，应在 set_config 前检查值。
使用 where id::text = 'undefined' 来避免错误有什么问题？
这种写法不会报错，但会导致全表扫描，因为对列进行类型转换会使主键索引失效。在 10 万行的表上会读取所有行。正确的做法是修复传入的值，而不是修改比较方式。
