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 相同的格式。請參閱上面的範例。 options 散列用於附加到建立表格定義的片段，例如「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)：將時間戳記（created_at 和 updated_at）欄位新增到 table_name。

修改

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)：移除由 ref_name 指定的 table_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

然後將列印短語「正在更新薪水...」，以及區塊完成時的區塊基準測試。

帶時間戳記的遷移

預設情況下，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 中，您仍然可以開啟自己的交易。

命名空間