Android Room外键约束表插入数据报SQLiteConstraintException问题排查

异常现象 #

开发过程中向Room自定义数据库插入数据时，抛出android.database.sqlite.SQLiteConstraintException: FOREIGN KEY constraint failed (code 787)，同时关联外键表的对应字段为空。

问题根因 #

• 插入顺序逻辑颠倒：当前代码先插入子表Playlist，再插入作为父表的User（对应memoTable）。SQLite外键约束要求被引用的父表数据必须先持久化到数据库，才能被子表关联，否则直接触发校验失败。
• 自增主键取值时机错误：代码提前在User未插入数据库时，就调用user.getId()给Playlist的外键字段赋值。由于User的id是Room配置的自动生成主键，未插入前这个值是对象默认的0，既不是数据库真实分配的id，也因为父表不存在id为0的记录，无法通过外键校验。
• 实体设计冗余：User类中用@Embedded注解内嵌了Playlist对象，这个注解会把Playlist的所有字段平铺到memoTable的列结构里，和单独建立Playlist表做一对多关联的逻辑冲突，容易造成字段映射混乱。
• 迁移语句和实体定义不匹配：手动编写的2到3版本迁移建表语句，没有和@ForeignKey注解声明的约束完全对齐，比如外键字段没有加NOT NULL约束，搭配全局的fallbackToDestructiveMigration逻辑，容易出现表结构和实体定义不一致的问题。
• 实体setter方法不符合规范：Playlist类的setPlaylistname方法返回值为String，不符合Java Bean的setter标准（setter需返回void），可能导致Room无法正确识别字段映射。

修复方案 #

1. 调整DAO方法的返回值，获取插入后的真实自增id
   Room的@Insert方法支持返回long类型，对应SQLite插入成功后生成的真实主键id，修改DAO定义：

@Dao
public interface UserDao {
    // 返回插入User后生成的真实id
    @Insert
    long insert(User user);

    // 返回插入Playlist后生成的真实id
    @Insert
    long insertPlayList(Playlist playlist);
}

2. 修正业务层的插入顺序
   替换原有的错误插入逻辑，严格按照先父表、后子表的顺序执行：

// 先赋值User的基础字段
user.setTitle(title);
user.setDescription(description);
user.setDate(currentData);
// 先插入父表User，拿到数据库分配的真实id
long realUserId = db.userDao().insert(user);
// 用真实的父表id给子表的外键字段赋值
playlist.setPlaylistname(title);
playlist.setUserCreatorId((int) realUserId);
// 最后插入子表Playlist，此时父表已存在对应id的记录，可通过外键校验
db.userDao().insertPlayList(playlist);

3. 移除User类中冗余的内嵌字段
   删除User类里@Embedded public Playlist playlist;这段代码，因为已经通过单独的Playlist表和@Relation注解实现了User和Playlist的一对多关联，不需要把Playlist的字段平铺到memoTable中，避免字段冲突。
4. 对齐迁移逻辑
   Room会根据@Entity注解自动生成符合要求的表结构，无需手动编写CREATE TABLE语句。如果需要保留迁移逻辑，要确保手动建表的字段、约束和实体类完全一致，比如给userCreatorId加上NOT NULL约束，和外键定义对齐。
5. 修正实体setter方法
   把Playlist类中setPlaylistname的返回值修改为void，符合Room的字段映射要求：

// 修正后的标准setter方法
public void setPlaylistname(String playlistname) {
    this.playlistname = playlistname;
}

核心注意点 #

SQLite外键校验默认强制开启，只要子表的外键值在父表中不存在，就会抛出code 787的约束异常，开发时需要遵守两个基本规则：

• 数据插入顺序永远是先父表，后子表
• 子表的外键字段，必须使用父表插入成功后返回的真实主键值，不能在父表未插入前提前取值赋值

内容的提问来源于stack exchange，提问作者동네한바퀴