Persistent的upsert功能异常求助（Postgres 9.5 + Yesod应用场景）

嘿，我来帮你梳理下Persistent框架的upsert功能在Postgres 9.5里的工作逻辑，还有你代码里可能需要注意的细节～

首先得明确：Persistent的upsert本质是封装了Postgres 9.5引入的INSERT ... ON CONFLICT DO UPDATE（或DO NOTHING）语法。你调用upsert时，Persistent会根据你的参数自动生成对应的SQL语句，这是理解它工作机制的核心。

你的代码里的核心细节 #

看你写的upsert i []，这里两个参数的作用很关键：

• 第一个参数i：是你要插入/更新的IntensiveTreatmentClient实体对象。
• 第二个参数[]：这是冲突发生时要更新的字段列表——你现在传了空列表，意味着如果遇到主键/唯一约束冲突，Persistent不会更新任何字段，只会返回数据库里已存在的那一行。这大概率是你产生困惑的点之一！

举个实际例子 #

假设你的IntensiveTreatmentClient实体定义有主键clientId，还有clientName、lastUpdated字段：

• 如果数据库里已经有clientId=123的行，你调用upsert (IntensiveTreatmentClient 123 "NewName" now()) []，Persistent生成的SQL大概是这样：

INSERT INTO intensive_treatment_client (client_id, client_name, last_updated)
VALUES (123, 'NewName', '2024-05-20T10:00:00')
ON CONFLICT (client_id) DO NOTHING
RETURNING *;

这种情况下，数据库不会做任何更新，直接返回原来的行。

• 如果你想在冲突时更新指定字段，就要把要更新的字段放进第二个参数里，比如：

upsert i 
  [ IntensiveTreatmentClientClientName =. clientName i
  , IntensiveTreatmentClientLastUpdated =. now()
  ]

这时候Persistent会生成带ON CONFLICT DO UPDATE的SQL，更新你指定的字段。

冲突约束的选择 #

Persistent的upsert默认会用实体的主键作为冲突检测的依据。如果你的实体有其他唯一约束（比如某个字段标记了Unique），你需要用upsertBy函数来明确指定冲突目标，比如：

-- 假设你定义了UniqueClientEmail约束
row <- runDB $ upsertBy 
  (UniqueClientEmail $ clientEmail i) 
  i 
  [ IntensiveTreatmentClientClientName =. clientName i
  ]

这样Persistent会针对client_email这个唯一约束来检测冲突，而不是主键。

Postgres 9.5 的限制要注意 #

Postgres 9.5的ON CONFLICT有个硬性要求：只能针对主键或唯一约束进行冲突检测，普通索引不行。所以你要确保你的IntensiveTreatmentClient实体对应的数据库表，有正确的主键或唯一约束定义，否则upsert会直接报错。

• 查看生成的SQL：在Yesod里开启SQL日志，能直观看到Persistent实际执行的SQL。只要在配置文件里把logLevel设为LevelDebug，运行应用后就能在控制台看到每条执行的SQL语句，这是排查问题的利器。
• 检查实体定义：确认你的IntensiveTreatmentClient实体的主键/唯一约束是否正确。比如类似这样的定义：

share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persistLowerCase|
IntensiveTreatmentClient
    clientId Int
    clientName Text
    clientEmail Text Unique
    lastUpdated UTCTime
    Primary clientId
|]

这里的Primary clientId和Unique约束就是upsert依赖的冲突检测依据。

• 分场景测试：分别测试“插入新行”和“冲突更新”两种情况，观察返回的row是否符合预期。比如先插入一行，再用相同主键调用upsert，看看返回的是原数据还是更新后的数据。

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