活动记录迁移

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

简单迁移示例

class AddSsl < ActiveRecord::Migration[7.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[7.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 表，然后使用依赖于该表的活动记录模型在其中创建第一行。它还使用了更高级的 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。可以通过传递一个选项哈希（如 { 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 上为 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(name)：删除名为 name 的表。
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[7.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[7.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

然后将打印短语“更新工资……”，以及块完成时的块基准。

带时间戳的迁移

默认情况下，Rails 生成的迁移看起来像

20080717013526_your_migration_name.rb

前缀是生成时间戳（UTC）。

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

config.active_record.timestamped_migrations = false

在 application.rb 中。

可逆迁移

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

要定义可逆迁移，请在迁移中像这样定义 change 方法

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

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

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

命名空间

MODULE ActiveRecord::Migration::Compatibility
CLASS ActiveRecord::Migration::CheckPending
CLASS ActiveRecord::Migration::CommandRecorder

方法

#

[]

A

announce

C

check_all_pending!,
check_pending!,
connection,
copy,
current_version

D

disable_ddl_transaction!,
down

E

exec_migration,
execution_strategy

L

load_schema_if_pending!

M

method_missing,
migrate,
migrate

N

new,
next_migration_number

P

proper_table_name

R

reversible,
revert,
reverting?,
run

S

say,
say_with_time,
suppress_messages

U

up,
up_only

W

write

属性

[RW]	name
[RW]	version

类公共方法

[](version) 链接

源代码：显示 | 在 GitHub 上

# File activerecord/lib/active_record/migration.rb, line 613
def self.[](version)
  Compatibility.find(version)
end

check_all_pending!() 链接

如果在环境中的所有数据库配置中任何迁移都处于待处理状态，则引发 ActiveRecord::PendingMigrationError 错误。

源代码：显示 | 在 GitHub 上

# File activerecord/lib/active_record/migration.rb, line 698
def check_all_pending!
  pending_migrations = []

  ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection_for_each(env: env) do |connection|
    if pending = connection.migration_context.open.pending_migrations
      pending_migrations << pending
    end
  end

  migrations = pending_migrations.flatten

  if migrations.any?
    raise ActiveRecord::PendingMigrationError.new(pending_migrations: migrations)
  end
end

check_pending!(connection = ActiveRecord::Tasks::DatabaseTasks.migration_connection) 链接

如果任何迁移处于待处理状态，则引发 ActiveRecord::PendingMigrationError 错误。

此方法已弃用，建议使用 check_all_pending!

源代码：显示 | 在 GitHub 上

# File activerecord/lib/active_record/migration.rb, line 682
      def check_pending!(connection = ActiveRecord::Tasks::DatabaseTasks.migration_connection)
        ActiveRecord.deprecator.warn(<<-MSG.squish)
          The `check_pending!` method is deprecated in favor of `check_all_pending!`. The
          new implementation will loop through all available database configurations and find
          pending migrations. The prior implementation did not permit this.
        MSG

        pending_migrations = connection.migration_context.open.pending_migrations

        if pending_migrations.any?
          raise ActiveRecord::PendingMigrationError.new(pending_migrations: pending_migrations)
        end
      end

current_version() 链接

源代码：显示 | 在 GitHub 上

# File activerecord/lib/active_record/migration.rb, line 617
def self.current_version
  ActiveRecord::VERSION::STRING.to_f
end

disable_ddl_transaction!() 链接

禁用包裹此迁移的事务。即使在调用 disable_ddl_transaction 后，您仍然可以创建自己的事务！

有关更多详细信息，请阅读“事务迁移”部分。

类 ActiveRecord::Migration < Object

活动记录迁移

可用转换

创建

修改

删除

不可逆转换

在 Rails 中运行迁移

更多示例

在更改表后使用模型

控制详细程度

带时间戳的迁移

可逆迁移

事务迁移

属性

类公共方法

[](version) 链接

check_all_pending!() 链接

check_pending!(connection = ActiveRecord::Tasks::DatabaseTasks.migration_connection) 链接

current_version() 链接

disable_ddl_transaction!() 链接

load_schema_if_pending!() 链接

migrate(direction) 链接

new(name = self.class.name, version = nil) 链接

实例公共方法

announce(message) 链接

connection() 链接

copy(destination, sources, options = {}) 链接

down() 链接

exec_migration(conn, direction) 链接

execution_strategy() 链接

method_missing(method, *arguments, &block) 链接

migrate(direction) 链接

next_migration_number(number) 链接

proper_table_name(name, options = {}) 链接

reversible() 链接

revert(*migration_classes, &block) 链接

reverting?() 链接

run(*migration_classes) 链接

say(message, subitem = false) 链接

say_with_time(message) 链接

suppress_messages() 链接

up() 链接

up_only(&block) 链接

write(text = "") 链接