使用Android Room @Upsert时触发UNIQUE constraint failed错误排查

问题概述 #

使用Android Room的@Upsert批量操作时触发唯一约束冲突错误：

net.sqlcipher.database.SQLiteConstraintException: error code 19: UNIQUE constraint failed with : appointment.activity_id

预期@Upsert会对已存在主键的记录执行更新，不存在的执行插入，但实际却触发了重复插入的约束错误。

实体类定义 #

data class AppointmentEntity(

   @PrimaryKey
   @field:ColumnInfo(name = "activity_id")
   val activityId: Long,

   @field:ColumnInfo(name = "selected_owner")
   val selectedOwner: String,

   val activityStartTimestamp: Instant,

   val activityEndTimestamp: Instant,

   val activityRevisionTimestamp: Instant?,

   val appointmentTypeCode: AppointmentTypeCode,

   val contactName: String?,

   val activityDescription: String?,

   val recurringId: Long?,

   val cancelled: Boolean,

   val personalAppointment: Boolean,

   val outlookIndicator: Boolean,

   val allDayEvent: Boolean,

   val deleteDate: Instant?
 )

DAO方法 #

@Upsert
fun insertAppointments(appointment: List<AppointmentEntity>)

官方文档说明（中文翻译） #

如果目标实体包含自动生成的主键，那么POJO类不需要包含相同的主键字段；否则，主键必须存在于POJO中。如果主键已存在，仅会更新部分实体字段所对应的列。

可能的原因及修复方案 #

1. SQLCipher与Room @Upsert的兼容性问题 #

Room的@Upsert底层依赖SQLite的冲突处理逻辑，但SQLCipher加密数据库在处理批量INSERT OR REPLACE/INSERT OR UPDATE时可能存在兼容性缺陷，导致更新逻辑未被触发，转而执行重复插入。

• 修复方案：替换@Upsert为@Insert(onConflict = OnConflictStrategy.REPLACE)，手动指定冲突替换策略：

  @Insert(onConflict = OnConflictStrategy.REPLACE)
  fun insertAppointments(appointment: List<AppointmentEntity>)
  

2. 传入列表存在重复主键 #

如果待插入的List<AppointmentEntity>中包含多个相同activityId的实体，Room在批量处理时会依次执行操作：第一个实体插入/更新成功后，第二个相同主键的实体触发插入时，会因为主键已存在而抛出约束错误。

• 修复方案：对传入列表按activityId去重，确保每个主键值在列表中唯一：

  val uniqueAppointments = appointment.distinctBy { it.activityId }
  dao.insertAppointments(uniqueAppointments)
  

3. Room版本存在bug #

旧版本Room（如2.4.x及更早）在批量@Upsert的逻辑实现上存在漏洞，无法正确识别已存在的主键记录。

• 修复方案：升级Room依赖到最新稳定版本，例如：

  implementation "androidx.room:room-runtime:2.6.1"
  kapt "androidx.room:room-compiler:2.6.1"
  // 同步升级SQLCipher对应的Room依赖
  implementation "androidx.room:room-sqlcipher:2.6.1"
  

4. Instant类型转换器异常 #

实体中使用的Instant类型需要对应的TypeConverter完成与数据库字段的双向转换。如果转换器实现错误（如时间戳转换丢失精度、空值处理异常），会导致Room无法正确匹配已存在的主键记录，进而尝试重复插入。

• 修复方案：检查并修正TypeConverter的实现逻辑：

  class InstantConverter {
      @TypeConverter
      fun fromInstant(instant: Instant?): Long? {
          return instant?.toEpochMilli()
      }
  
      @TypeConverter
      fun toInstant(timestamp: Long?): Instant? {
          return timestamp?.let { Instant.ofEpochMilli(it) }
      }
  }
  

  同时确保在RoomDatabase类中添加@TypeConverters(InstantConverter::class)注解。

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