当前位置：首页 > news >正文

如何安全添加带默认值的列？online_migrations背景填充功能实战教程

news 2026/7/25 22:10:26

如何安全添加带默认值的列？online_migrations背景填充功能实战教程

【免费下载链接】online_migrationsCatch unsafe PostgreSQL migrations in development and run them easier in production (code helpers for table/column renaming, changing column type, adding columns with default, background migrations, etc).项目地址: https://gitcode.com/gh_mirrors/on/online_migrations

在PostgreSQL数据库开发中，为大型表添加带默认值的列可能导致长时间锁表，影响生产环境稳定性。online_migrations提供的add_column_with_default方法和背景数据迁移功能，能够帮助开发者安全、高效地完成这一操作。本文将详细介绍如何利用这些工具实现零停机添加带默认值的列。

为什么直接添加默认值列很危险？

传统的add_column :table, :column, :type, default: value命令在PostgreSQL中会触发全表扫描，为每一行设置默认值。当表数据量达到百万甚至千万级时，这个过程可能持续数小时，期间表会被锁定，导致应用无法读写数据。

online_migrations的add_column_with_default方法通过以下步骤解决这个问题：

先添加允许NULL的列
异步背景填充默认值
最后设置NOT NULL约束（如果需要）

快速上手：add_column_with_default基础用法

基本语法

add_column_with_default :users, :admin, :boolean, default: false

这个简单的命令会自动处理所有复杂的背景填充逻辑。如果需要禁止NULL值，可以添加null: false选项：

add_column_with_default :users, :status, :integer, default: 0, null: false

高级配置选项

你还可以自定义批处理大小和暂停时间，优化数据库负载：

add_column_with_default :users, :admin, :boolean, default: false, batch_size: 10_000, # 每次处理10000行 pause_ms: 100 # 每批处理后暂停100毫秒

完整的参数说明可查看schema_statements.rb源码。

背景数据迁移深度实战

什么是背景数据迁移？

背景数据迁移用于处理大型表的数据更新，通过分批处理避免长时间锁表。它特别适合以下场景：

为新添加的列填充历史数据
从JSON字段迁移数据到独立列
批量更新关联表数据

详细指南可参考官方文档background_data_migrations.md。

创建背景数据迁移

使用生成器创建迁移文件：

$ bin/rails generate online_migrations:data_migration backfill_project_issues_count

这会生成两个文件：

数据迁移逻辑文件：lib/online_migrations/data_migrations/backfill_project_issues_count.rb
任务调度文件：db/migrate/xxxxxxxxxxxxxx_enqueue_backfill_project_issues_count.rb

实现迁移逻辑

编辑生成的迁移文件，实现collection和process方法：

# lib/online_migrations/data_migrations/backfill_project_issues_count.rb module OnlineMigrations module DataMigrations class BackfillProjectIssuesCount < OnlineMigrations::DataMigration class Project < ActiveRecord::Base; end def collection Project.in_batches(of: 100) # 分批处理，每批100条 end def process(relation) relation.update_all(<<~SQL) issues_count = ( SELECT COUNT(*) FROM issues WHERE issues.project_id = projects.id ) SQL end def count collection.count # 总批次数，用于进度显示 end end end end

配置调度器

使用whenever gem配置定时任务，定期执行背景迁移：

# config/schedule.rb every 1.minute do runner "OnlineMigrations.run_background_data_migrations" end

监控与调优

事件订阅

通过ActiveSupport通知监控迁移进度：

ActiveSupport::Notifications.subscribe("started.background_data_migrations") do |name, start, finish, id, payload| Rails.logger.info "Migration started: #{payload[:migration].name}" end ActiveSupport::Notifications.subscribe("completed.background_data_migrations") do |name, start, finish, id, payload| Rails.logger.info "Migration completed: #{payload[:migration].name} in #{finish - start}s" end

性能调优建议

合理设置批处理大小：根据服务器性能调整，建议从1000行开始测试
添加适当暂停：避免数据库负载过高，通常设置100-500ms
监控数据库性能：使用pg_stat_activity查看锁等待情况
错峰执行：选择业务低峰期运行大型迁移

常见问题解决方案

迁移卡住怎么办？

online_migrations会自动处理卡住的迁移，默认超时时间可通过配置调整：

# config/initializers/online_migrations.rb OnlineMigrations.config.background_data_migrations.stuck_timeout = 30.minutes

如何处理迁移错误？

自定义错误处理逻辑：

OnlineMigrations.config.background_data_migrations.error_handler = ->(error, migration) do # 发送告警通知 ErrorNotifier.notify(error, migration: migration.name) end