Rails 迁移中 schema 缓存失效问题:用 reset_column_information 让数据迁移使用最新表结构

原创2026-10-08 11:56:521,903 阅读
文章标签:文档教程知识管理

Rails 迁移中 schema 缓存失效问题:用 reset_column_information 让数据迁移使用最新表结构

导读

在真实世界的 Rails 项目中,迁移(migration)往往不只是改表结构,还会同步搬运数据——典型场景是把一列数据从一张表挪到另一张表。本文以 Rails 项目中「将 authors 表的 genre 列迁移到 books 表」这一实战案例为主线,剖析一个极易踩坑的隐蔽问题:ActiveRecord 出于性能考虑缓存了模型对应的表结构,导致同一迁移里新增的列对模型「不可见」,数据更新静默失败。读完本文,你将理解 schema 缓存(schema cache)的工作原理、掌握 reset_column_information 的正确使用时机,并学会如何验证迁移中的数据是否真正写入目标列。

问题场景:同一迁移里既改结构又搬数据

真实的业务迁移经常会同时包含 schema 变更 和 数据变更。一个非常典型的例子是「把一列数据从一张表移动到另一张表」:你需要先给目标表加一个新列,然后把源表的数据搬过去,最后删掉源表的旧列。

假设当前有两个模型,分别对应 authors 表和 books 表:

# GenericAuthor for table 'authors'
# GenericBook for table 'books'

我们想把每位作者的 genre 从 authors 表搬到 books 表,一个看起来很直接的迁移是这样写的:

def up
  add_column :books, :genre, :string

  GenericAuthor.find_each do |author|
    book = GenericBook.find_by(author_id: author.id)
    book.update!(genre: author.genre)
  end

  remove_column :authors, :genre
end

这段代码的逻辑看起来无懈可击:

  1. add_column :books, :genre, :string —— 给 books 表新增 genre 字符串列;
  2. 用 GenericAuthor.find_each 逐批遍历所有作者(关于 find_each 的分批加载机制,可参考 load-records-in-batches-with-find-each.md,它底层通过 find_in_batches 每次只加载 1000 条记录进内存,避免大数据量迁移时内存爆炸);
  3. 根据 author_id 找到对应的书,把作者的 genre 写进 book;
  4. 最后 remove_column :authors, :genre 删掉旧列。

然而实际执行后你会发现:books 表里新加的 genre 列 没有任何数据被写入,迁移看似成功、实际数据全丢。

根因:ActiveRecord 缓存的旧 schema 让新列「隐身」

问题出在 ActiveRecord 的 schema 缓存 机制上。

作为一个性能优化,ActiveRecord 在模型第一次被使用时,会把该模型对应数据表的列信息(列名、类型、默认值等)从数据库加载进来,并缓存在模型类上。之后的查询、属性读写都直接基于这份缓存,不再每次打数据库询问表结构。

这意味着:迁移在同一进程内先执行了 add_column,但 GenericBook 模型此时可能已经持有 没有 genre 列的旧版 schema 缓存。于是 book.update!(genre: author.genre) 这类 ActiveRecord 修改操作,实际上是基于一份「不认识 genre 列」的 schema 在工作——更新被静默忽略(在严格模式下可能表现为 unknown attribute 异常),数据自然就没有被搬运过去。

从仓库中 get-the-column-names-for-a-model.md 可以看到,模型暴露了 column_names 类方法用于查看其缓存/加载的列信息:

> Book.column_names
=> ["id", "title", "publication_year", "created_at", "updated_at", "author_id", "genre"]

可以利用这一点来验证缓存的列信息是否已更新——在 add_column 之后、执行数据更新之前,检查 GenericBook.column_names 是否已经包含 "genre",如果没有,就说明模型还在使用旧版缓存。

解法:调用 reset_column_information 刷新表结构缓存

要确保 ActiveRecord 使用最新的列信息,只需在结构变更之后、数据操作之前,对受影响的模型调用 reset_column_information:

def up
  add_column :books, :genre, :string

  GenericBook.reset_column_information

  GenericAuthor.find_each do |author|
    book = GenericBook.find_by(author_id: author.id)
    book.update!(genre: author.genre)
  end

  remove_column :authors, :genre
end

reset_column_information 的作用是清空模型上缓存的 schema 信息。调用之后,下一次 ActiveRecord 访问该模型的列信息时,会重新从数据库拉取最新表结构,此时新添加的 genre 列就会被正确识别,book.update!(genre: ...) 也能真正把数据写入 books 表。

什么时候需要调用?

需要特别注意的关键点是:迁移执行过程中,模型类已经在同一进程内被加载过。只要满足这个前提,就会触发缓存问题。具体来说:

  • 迁移里先 add_column / change_column 等结构变更,随后又通过 ActiveRecord 模型读写新列的数据;
  • 迁移中引用了任何在迁移执行前就已经被加载进内存的模型类(Rails 的迁移机制在加载迁移文件时,也常会连带加载相关模型常量)。

在结构变更后、数据操作前,对所有受影响的模型(尤其是表结构发生变化的表所对应的模型)调用 reset_column_information,是最稳妥的防御姿势。

延伸:如何验证迁移确实搬运了数据

迁移写完并跑通后,建议做一次自证,而不是只凭「没有报错」就认为成功。几种常见验证手段:

  1. 在数据库层面直接查询,确认 books 表的 genre 列有值、authors 表的 genre 列已清空。仓库中的 get-active-record-attribute-directly-from-database.md 提到,ActiveRecord 模型会自动为每个数据库列生成对应的访问方法,因此也可以在 console 里直接抽查:
GenericBook.where.not(genre: nil).count
GenericAuthor.where.not(genre: nil).count   # 期望为 0
  1. 检查迁移是否可回滚。本案例的 up 中包含了 remove_column :authors, :genre,参照 make-remove-column-migration-reversible.md:remove_column 默认并不真正可逆,Rails 在回滚时无法得知该列的类型,除非在调用时补上类型参数。更关键的是,remove_column 一旦执行就会永久丢弃该列的全部数据,所以在部署此类迁移前,务必确认 authors.genre 的数据已经被完整搬运,否则数据将无法找回。

  2. 整体跑一遍 up/down 双方向。仓库中的 migrating-up-down-up.md 给出了一个实用的验证习惯:

rails db:migrate && rails db:migrate:redo

db:migrate 验证 up 方向正常执行,db:migrate:redo 先回滚再重新迁移,验证 down 方向也能正常工作。对于含数据搬运的迁移,尤其要确认回滚时数据不会破坏原始表。若需要绕过迁移表检查、手动执行某个迁移的 up/down,可以参考 manually-run-a-migration-from-rails-console.md 中的 console 手法。

小结

要点 说明
触发条件 迁移在同一进程中先改表结构,再通过已加载的模型读写新列
根因 ActiveRecord 为性能缓存了模型对应表的 schema(列信息),新列对旧缓存不可见
解决方式 结构变更后、数据操作前调用 GenericBook.reset_column_information
验证方式 用 column_names 检查缓存列信息、直接查询数据库核对数据、用 db:migrate:redo 验证 up/down
注意事项 remove_column 不可逆且会永久丢弃数据,务必确认数据已搬迁完毕

核心经验只有一句话:在同一个迁移里,凡是「先改表结构、再用 ActiveRecord 模型操作新列」的场景,都要记得在结构变更与数据操作之间调用 reset_column_information,让模型从数据库重新加载最新 schema,避免数据迁移在静默中丢失。

登录后查看全文
til