Миграции 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. См. пример выше. Хеш параметров предназначен для фрагментов вроде «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, имеющий по умолчанию тип integer. Подробнее см. в разделе 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): Задаёт для column_name значение по умолчанию, определённое через default_or_changes, в таблице table_name. Передача хеша, содержащего :from и :to, в качестве default_or_changes позволит отменить это изменение при откате миграции.

• change_column_null(table_name, column_name, null, default = nil): Устанавливает или удаляет ограничение NOT NULL для column_name. Флаг 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): Удаляет столбец с именем column_name из таблицы table_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) из определения таблицы.

Необратимые преобразования

Некоторые преобразования являются разрушительными и не могут быть отменены. Такие миграции должны вызывать исключение ActiveRecord::IrreversibleMigration в методе down.

Запуск миграций из Rails

В пакет Rails входят несколько инструментов для создания и применения миграций.

Чтобы создать новую миграцию, используйте

$ bin/rails generate migration MyNewMigration

где MyNewMigration — имя миграции. Генератор создаст пустой файл миграции timestamp_my_new_migration.rb в каталоге db/migrate/, где 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, этот шаг завершится с ошибкой, и вам придётся выполнить некоторые действия вручную.

Другие примеры

Не все миграции изменяют схему. Некоторые лишь исправляют данные:

class RemoveEmptyTags < ActiveRecord::Migration[8.1]
  def up
    Tag.all.each { |tag| tag.destroy if tag.pages.empty? }
  end

  def down
    # not much we can do to restore deleted data
    raise ActiveRecord::IrreversibleMigration, "Can't recover the deleted tags"
  end
end

Другие при применении миграции удаляют столбцы, а не при её откате:

class RemoveUnnecessaryItemAttributes < ActiveRecord::Migration[8.1]
  def up
    remove_column :items, :incomplete_items_count
    remove_column :items, :completed_items_count
  end

  def down
    add_column :items, :incomplete_items_count
    add_column :items, :completed_items_count
  end
end

А иногда нужно выполнить SQL-команду, для которой в миграциях нет прямой абстракции:

class MakeJoinUnique < ActiveRecord::Migration[8.1]
  def up
    execute "ALTER TABLE `pages_linked_pages` ADD UNIQUE `page_id_linked_page_id` (`page_id`,`linked_page_id`)"
  end

  def down
    execute "ALTER TABLE `pages_linked_pages` DROP INDEX `page_id_linked_page_id`"
  end
end

Использование модели после изменения её таблицы

Иногда нужно добавить столбец в миграции и сразу же заполнить его. В этом случае необходимо вызвать 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

После завершения блока будет выведена фраза «Обновление зарплат…» вместе с замером времени его выполнения.

Миграции с временными метками

По умолчанию 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 определит, как выполнить для вас команды отката.

Чтобы определить обратимую миграцию, добавьте в неё метод 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

Помните, что вы по-прежнему можете открывать собственные транзакции, даже если находитесь в Migration с self.disable_ddl_transaction!.