Active Record 迁移

迁移可以管理多个物理数据库使用的模式的演变。它解决了一个常见的问题，即在本地数据库中添加一个字段以使新功能工作，但又不确定如何将该更改推送到其他开发人员和生产服务器。使用迁移，您可以描述自包含类中的转换，这些类可以检入版本控制系统并在可能落后一、二或五个版本的另一个数据库上执行。

简单迁移示例

class AddSsl < ActiveRecord::Migration[8.0]
  def up
    add_column :accounts, :ssl_enabled, :boolean, default: true
  end

  def down
    remove_column :accounts, :ssl_enabled
  end
end

此迁移将为 accounts 表添加一个布尔型标志，如果要撤销迁移，则将其删除。它展示了所有迁移如何具有两个方法 up 和 down，它们描述了实现或删除迁移所需的转换。这些方法可以包含迁移特定方法（如 add_column 和 remove_column），但也可以包含用于生成转换所需数据的常规 Ruby 代码。

需要初始化数据的更复杂迁移的示例

class AddSystemSettings < ActiveRecord::Migration[8.0]
  def up
    create_table :system_settings do |t|
      t.string  :name
      t.string  :label
      t.text    :value
      t.string  :type
      t.integer :position
    end

    SystemSetting.create  name:  'notice',
                          label: 'Use notice?',
                          value: 1
  end

  def down
    drop_table :system_settings
  end
end

此迁移首先添加 system_settings 表，然后使用依赖于该表的 Active Record 模型在其中创建第一行。它还使用更高级的 create_table 语法，您可以在其中在一个块调用中指定完整的表模式。

可用的转换

创建

create_join_table(table_1, table_2, options): 创建一个连接表，其名称为前两个参数的词法顺序。有关详细信息，请参见 ActiveRecord::ConnectionAdapters::SchemaStatements#create_join_table。
create_table(name, options): 创建一个名为 name 的表，并将表对象提供给一个块，然后可以使用该块向其中添加列，遵循与 add_column 相同的格式。请参见上面的示例。选项哈希用于“DEFAULT CHARSET=UTF-8”等片段，这些片段附加到创建表定义。
add_column(table_name, column_name, type, options): 向名为 table_name 的表添加一个新列，该列名为 column_name，指定为以下类型之一：:string、:text、:integer、:float、:decimal、:datetime、:timestamp、:time、:date、:binary、:boolean。可以通过传递一个 options 哈希（如 { default: 11 }）来指定默认值。其他选项包括 :limit 和 :null（例如 { limit: 50, null: false }）– 有关详细信息，请参见 ActiveRecord::ConnectionAdapters::TableDefinition#column。
add_foreign_key(from_table, to_table, options): 添加一个新的外键。from_table 是具有键列的表，to_table 包含引用的主键。
add_index(table_name, column_names, options): 添加一个新的索引，其名称为列名。其他选项包括 :name、:unique（例如 { name: 'users_name_index', unique: true }）和 :order（例如 { order: { name: :desc } }）。
add_reference(:table_name, :reference_name): 默认情况下，添加一个名为 reference_name_id 的新列，该列为整数。有关详细信息，请参见 ActiveRecord::ConnectionAdapters::SchemaStatements#add_reference。
add_timestamps(table_name, options): 向 table_name 添加时间戳（created_at 和 updated_at）列。

修改

change_column(table_name, column_name, type, options): 使用与 add_column 相同的参数将列更改为不同的类型。
change_column_default(table_name, column_name, default_or_changes): 为 table_name 上的 default_or_changes 定义的 column_name 设置默认值。传递包含 :from 和 :to 的哈希作为 default_or_changes 将使此更改在迁移中可逆。
change_column_null(table_name, column_name, null, default = nil): 设置或删除 column_name 上的 NOT NULL 约束。null 标志指示该值是否可以为 NULL。有关详细信息，请参见 ActiveRecord::ConnectionAdapters::SchemaStatements#change_column_null。
change_table(name, options): 允许对名为 name 的表进行列更改。它使表对象可用于一个块，然后可以使用该块向其中添加/删除列、索引或外键。
rename_column(table_name, column_name, new_column_name): 重命名一个列，但保留类型和内容。
rename_index(table_name, old_name, new_name): 重命名一个索引。
rename_table(old_name, new_name): 将名为 old_name 的表重命名为 new_name。

删除

drop_table(*names): 删除给定的表。
drop_join_table(table_1, table_2, options): 删除由给定参数指定的连接表。
remove_column(table_name, column_name, type, options): 从名为 table_name 的表中删除名为 column_name 的列。
remove_columns(table_name, *column_names): 从表定义中删除给定的列。
remove_foreign_key(from_table, to_table = nil, **options): 从名为 table_name 的表中删除给定的外键。
remove_index(table_name, column: column_names): 删除由 column_names 指定的索引。
remove_index(table_name, name: index_name): 删除由 index_name 指定的索引。
remove_reference(table_name, ref_name, options): 删除 table_name 上由 ref_name 指定的引用。
remove_timestamps(table_name, options): 从表定义中删除时间戳列（created_at 和 updated_at）。

不可逆的转换

某些转换以不可逆的方式具有破坏性。这种类型的迁移应该在它们的 down 方法中引发 ActiveRecord::IrreversibleMigration 异常。

从 Rails 中运行迁移

Rails 包含几个工具来帮助创建和应用迁移。

要生成一个新的迁移，可以使用

$ bin/rails generate migration MyNewMigration

其中 MyNewMigration 是迁移的名称。生成器将在 db/migrate/ 目录中创建一个空的迁移文件 timestamp_my_new_migration.rb，其中 timestamp 是迁移生成的 UTC 格式的日期和时间。

有一个特殊的语法快捷方式来生成将字段添加到表的迁移。

$ bin/rails generate migration add_fieldname_to_tablename fieldname:string

这将生成文件 timestamp_add_fieldname_to_tablename.rb，它将如下所示

class AddFieldnameToTablename < ActiveRecord::Migration[8.0]
  def change
    add_column :tablenames, :fieldname, :string
  end
end

要针对当前配置的数据库运行迁移，请使用 bin/rails db:migrate。这将通过运行所有待处理的迁移来更新数据库，如果缺失，则创建 schema_migrations 表（参见下面的“关于 schema_migrations 表”部分）。它还将调用 db:schema:dump 命令，该命令将更新您的 db/schema.rb 文件以匹配数据库的结构。

要将数据库回滚到以前的迁移版本，请使用 bin/rails db:rollback VERSION=X，其中 X 是您希望降级的版本。或者，如果您希望回滚最近的几个迁移，也可以使用 STEP 选项。bin/rails db:rollback STEP=2 将回滚最近的两个迁移。

如果任何迁移引发了 ActiveRecord::IrreversibleMigration 异常，则该步骤将失败，您将需要执行一些手动操作。

在更改其表后使用模型

有时您想在迁移中添加一个列，并在添加后立即填充它。在这种情况下，您需要调用 Base#reset_column_information 以确保模型具有添加新列后的最新列数据。示例

class AddPeopleSalary < ActiveRecord::Migration[8.0]
  def up
    add_column :people, :salary, :integer
    Person.reset_column_information
    Person.all.each do |p|
      p.update_attribute :salary, SalaryCalculator.compute(p)
    end
  end
end

控制详细程度

默认情况下，迁移将描述它们正在执行的操作，并将它们写入到它们执行时控制台，以及描述每个步骤花费了多长时间的基准。

您可以通过设置 ActiveRecord::Migration.verbose = false 来使它们静音。

您还可以通过使用 say_with_time 方法插入自己的消息和基准

def up
  ...
  say_with_time "Updating salaries..." do
    Person.all.each do |p|
      p.update_attribute :salary, SalaryCalculator.compute(p)
    end
  end
  ...
end

然后将打印短语“Updating salaries…”，以及该块完成后该块的基准。

带时间戳的迁移

默认情况下，Rails 生成的迁移如下所示

20080717013526_your_migration_name.rb

前缀是一个生成时间戳（以 UTC 为单位）。时间戳不应手动修改。要验证迁移时间戳是否符合 Active Record 预期的格式，可以使用以下配置选项

config.active_record.validate_migration_timestamps = true

如果您更喜欢使用数字前缀，可以通过设置以下方式关闭带时间戳的迁移

config.active_record.timestamped_migrations = false

在 application.rb 中。

可逆的迁移

可逆的迁移是知道如何为您进行 down 的迁移。您只需提供 up 逻辑，Migration 系统就会为您找出如何执行 down 命令。

要定义一个可逆的迁移，请在您的迁移中定义 change 方法，如下所示

class TenderloveMigration < ActiveRecord::Migration[8.0]
  def change
    create_table(:horses) do |t|
      t.column :content, :text
      t.column :remind_at, :datetime
    end
  end
end

此迁移将为您创建 horses 表，并在向下迁移时自动找出如何删除该表。

某些命令无法反转。如果您想定义这些情况下如何向上和向下移动，则应该像以前一样定义 up 和 down 方法。

如果一个命令无法反转，则在迁移向下移动时会引发 ActiveRecord::IrreversibleMigration 异常。

有关可逆命令的列表，请参见 ActiveRecord::Migration::CommandRecorder。

事务性迁移

如果数据库适配器支持 DDL 事务，则所有迁移将自动包含在一个事务中。但是，有些查询无法在事务内执行，对于这些情况，您可以关闭自动事务。

class ChangeEnum < ActiveRecord::Migration[8.0]
  disable_ddl_transaction!

  def up
    execute "ALTER TYPE model_size ADD VALUE 'new_value'"
  end
end

请记住，即使您在使用 self.disable_ddl_transaction! 的 Migration 中，您仍然可以打开自己的事务。

命名空间

方法

#