TableMigrator 技术文档

1. 安装指南

将 TableMigrator 作为 Rails 插件安装：

./script/plugin install git://github.com/freels/table_migrator.git

2. 项目使用说明

TableMigrator 是一种在尽可能不影响正常运行时间的情况下，修改大型 MySQL 表的方法。它的基本原理是创建一个新表，并根据原表的结构进行修改，然后将原表中的每一行数据复制到新表中。在此过程中，原表保持可读可写状态，从而实现零停机迁移。

迁移流程

1. 创建一个新的表，结构与原表相同。
2. 对新表应用一个或多个 ALTER TABLE 语句。
3. 在不锁定原表的情况下，将原表中的数据复制到新表中。
4. 通过比对时间戳或版本号来识别在新表创建后发生变化的数据行。
5. 获取原表的写锁，将变化的数据行复制到新表中。
6. 释放写锁，将新表重命名为原表名。

注意事项

• 确保用于识别更新行的列（如 updated_at 或 created_at）上有索引，否则可能会造成停机时间。
• 如果在迁移过程中执行删除操作，这些删除将不会反映到新表中。为了避免这个问题，可以使用逻辑删除（软删除）。

3. 项目API使用文档

TableMigrator 提供了两种定义迁移的 API：

使用 change_table 方法

class AddStuffToMyBigTable < TableMigration

  migrates :users

  change_table do |t|
    t.integer :foo, :null => false, :default => 0
    t.string  :bar
    t.index   :foo, :name => 'index_for_foo'
  end
end

使用原始 SQL

class AddStuffToMyBigTable < TableMigration
  migrates :users

  schema_changes.push <<-SQL
    ALTER TABLE :new_table_name
    ADD COLUMN `foo` int(11) unsigned NOT NULL DEFAULT 0
  SQL

  schema_changes.push <<-SQL
    ALTER TABLE :new_table_name
    ADD COLUMN `bar` varchar(255)
  SQL

  schema_changes.push <<-SQL
    ALTER TABLE :new_table_name
    ADD INDEX `index_foo` (`foo`)
  SQL
end

高级迁移

可以使用常规的 ActiveRecord::Migration，并手动设置 TableMigrator 实例。

class AddStuffToMyBigTable < ActiveRecord::Migration

  def self.setup
    @tm = TableMigrator.new(:users,
      :migration_name => 'add_stuff',
      :multi_pass => true,
      :create_temp_table => true,
      :dry_run => false
    )

    @tm.schema_changes.push "ALTER TABLE :new_table_name ADD COLUMN `foo` int(11) unsigned NOT NULL DEFAULT 0"
    # 其他 schema_changes ...
  end

  def self.up
    self.setup
    @tm.up!
  end

  def self.down
    self.setup
    @tm.down!
  end
end

4. 项目安装方式

请按照以下步骤安装 TableMigrator：

1. 将 TableMigrator 作为 Rails 插件安装。
2. 根据需要创建迁移类，继承自 TableMigration 或 ActiveRecord::Migration。
3. 使用 change_table 方法或原始 SQL 定义迁移操作。
4. 执行迁移操作。

通过上述步骤，您可以实现对 MySQL 大型表的零停机迁移。