使用Rails保存新记录时外键约束失败问题排查

问题根源 #

1. 数据库外键约束与模型关联逻辑不匹配

   • 迁移文件中使用 t.references :sectioncode, foreign_key: {to_table: :sections}，默认会创建外键约束，让 spaces.sectioncode_id 关联 sections.id 字段。
   • 但模型中定义的关联是让 spaces.sectioncode_id 关联 sections.sectioncode 字段（通过 primary_key: :sectioncode）。
   • 你的Section记录id=4、sectioncode=1，插入sectioncode_id=1时，Rails环境中外键约束生效，数据库会检查sections.id是否存在值为1的记录，实际不存在，因此触发FOREIGN KEY constraint failed错误。

2. 手动执行SQL成功的原因
   SQLite默认禁用外键约束，你手动打开SQLite控制台时未执行PRAGMA foreign_keys = ON;启用外键，因此插入违反外键约束的记录不会报错；而Rails会自动启用SQLite外键约束，所以执行时会触发错误。

解决步骤 #

方案1：回滚并修正原迁移（未部署到生产环境时适用）

1. 回滚创建Spaces表的迁移：

   rails db:rollback
   

2. 修改迁移文件中的外键定义：

   # 替换原t.references行
   t.integer :sectioncode_id
   t.foreign_key :sections, column: :sectioncode_id, primary_key: :sectioncode
   

3. 重新执行迁移：

   rails db:migrate
   

方案2：添加新迁移修正外键约束（已部署时适用）

1. 生成新迁移文件：

   rails generate migration FixSpaceSectionForeignKey
   

2. 在新迁移文件中编写修正逻辑：

   class FixSpaceSectionForeignKey < ActiveRecord::Migration[7.0]
     def change
       # 移除旧的外键约束
       remove_foreign_key :spaces, :sections
       # 添加关联sections.sectioncode的新外键
       add_foreign_key :spaces, :sections, column: :sectioncode_id, primary_key: :sectioncode
     end
   end
   

3. 执行迁移：

   rails db:migrate
   

验证关联（推荐写法）

修正后，建议通过Rails关联方式创建记录，避免手动设置外键字段：

section = Section.find_by!(sectioncode: 1)
space = section.spaces.create(spacecode: 1, name: "S1 (Seeded)", description: "D1")

额外提示 #

• 尽量遵循Rails约定：优先使用表的id字段作为关联主键，可减少自定义配置带来的问题；仅当业务必须使用sectioncode作为关联键时，才手动指定primary_key和foreign_key。
• 检查SQLite外键状态：在SQLite控制台执行PRAGMA foreign_keys;，返回1表示外键已启用，0表示未启用。

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