Active Record 迁移¶ ↑

迁移可以管理多个物理数据库使用的模式的演进。它解决了常见的数据库变更问题：您在本地数据库中添加了一个字段来实现新功能，但又不确定如何将此更改推送到其他开发人员以及生产服务器。通过迁移，您可以将转换描述为独立的类，这些类可以检入版本控制系统并应用于可能落后一、二或五代的其他数据库。

一个简单迁移的示例

class AddSsl < ActiveRecord::Migration[8.1]
  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.1]
  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` 的格式添加列。请参阅上面的示例。options 哈希用于“DEFAULT CHARSET=UTF-8”等片段，这些片段将附加到 create table 定义的末尾。
add_column(table_name, column_name, type, options)：向名为 `table_name` 的表中添加一个名为 `column_name` 的新列，指定其类型为以下之一：:string, :text, :integer, :float, :decimal, :datetime, :timestamp, :time, :date, :binary, :boolean。可以通过传递一个像 { default: 11 } 这样的 options 哈希来指定默认值。其他选项包括 :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 上定义的 column_name 设置默认值 default_or_changes。将包含 :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.1]
  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.1]
  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

如果您希望使用数字前缀，可以通过在 `application.rb` 中设置以下选项来关闭带时间戳的迁移：

config.active_record.timestamped_migrations = false

在 application.rb 中。

可逆迁移¶ ↑

可逆迁移是可以自动执行 `down` 操作的迁移。您只需提供 `up` 逻辑，Migration 系统就会自动为您执行 `down` 命令。

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

class TenderloveMigration < ActiveRecord::Migration[8.1]
  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.1]
  disable_ddl_transaction!

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