PostgreSQL用INSERT搭配ON CONFLICT实现Upsert时报ON附近语法错误

• 触发本次语法错误的直接核心原因：你写的原SQL在VALUES(i, j, random);这一行末尾加了多余的分号，直接提前终止了整条INSERT语句。PostgreSQL执行到分号时，会认为前面的INSERT逻辑已经执行完成，后续紧跟的ON CONFLICT子句因为脱离了INSERT的上下文，会被识别为没有依附的非法语法片段，最终抛出“ON附近存在语法错误”的解析异常。日常开发中这类问题大多来自IDE/编辑器写SQL时的自动补全——很多工具会在你打完VALUES子句时自动插入一个分号，刚好把完整的UPSERT语句截断成两部分。
• 其他会导致UPSERT逻辑失效的潜在注意事项：
  • ON CONFLICT后指定的("IDWU_User1", "IDWU_User2")用户组合，必须在WU_MatchingUsers表上建立对应的联合唯一约束/联合唯一索引，否则即便语法修正完成，也会因为PostgreSQL无法识别冲突判定规则，抛出“无匹配冲突索引”的运行错误。
  • 取值部分如果是应用层传入的动态变量，不能直接写i、j作为占位符，需要替换为PostgreSQL兼容的绑定参数格式（比如$1、$2、$3）；如果要生成随机匹配分，需要以函数形式调用random()，直接写random会被数据库识别为不存在的字段名，触发未知列错误。

INSERT INTO "WU_MatchingUsers"("IDWU_User1", "IDWU_User2", "MatchingScore")
VALUES ($1, $2, random()) -- 此处绝对不能加任何语句结束用的分号
ON CONFLICT ("IDWU_User1", "IDWU_User2")
DO UPDATE SET "MatchingScore" = EXCLUDED."MatchingScore";

• 当表中不存在指定用户组合的匹配记录时，会正常插入新行，写入传入的两个用户ID和计算得到的匹配分数
• 当表中已存在相同用户组合的记录时，不会触发重复插入报错，只会将原有记录的MatchingScore字段值，替换为本次尝试插入的最新分数，完全匹配预期的更新逻辑。

内容的提问来源于stack exchange，提问作者Mathieu Arthur