Rails 迁移中 schema 缓存失效问题:用 reset_column_information 让数据迁移使用最新表结构
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
这段代码的逻辑看起来无懈可击:
add_column :books, :genre, :string—— 给books表新增genre字符串列;- 用
GenericAuthor.find_each逐批遍历所有作者(关于find_each的分批加载机制,可参考 load-records-in-batches-with-find-each.md,它底层通过find_in_batches每次只加载 1000 条记录进内存,避免大数据量迁移时内存爆炸); - 根据
author_id找到对应的书,把作者的genre写进book; - 最后
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,是最稳妥的防御姿势。
延伸:如何验证迁移确实搬运了数据
迁移写完并跑通后,建议做一次自证,而不是只凭「没有报错」就认为成功。几种常见验证手段:
- 在数据库层面直接查询,确认
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
-
检查迁移是否可回滚。本案例的
up中包含了remove_column :authors, :genre,参照 make-remove-column-migration-reversible.md:remove_column默认并不真正可逆,Rails 在回滚时无法得知该列的类型,除非在调用时补上类型参数。更关键的是,remove_column一旦执行就会永久丢弃该列的全部数据,所以在部署此类迁移前,务必确认authors.genre的数据已经被完整搬运,否则数据将无法找回。 -
整体跑一遍 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,避免数据迁移在静默中丢失。