Миграции Active Record

Миграции позволяют управлять эволюцией схемы, используемой несколькими физическими базами данных. Это решение распространенной проблемы добавления поля для новой функции в локальной базе данных, но при этом нет уверенности, как внести это изменение для других разработчиков и на сервере производства. С помощью миграций вы можете описать преобразования в автономных классах, которые могут быть включены в системы управления версиями и выполнены в другой базе данных, которая может быть на одну, две или пять версий позади.

Пример простой миграции:

class AddSsl < ActiveRecord::Migration[6.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[6.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): Добавляет столбцы отметки времени (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): Устанавливает значение по умолчанию для 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(name): Удаляет таблицу с именем name.

• 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[6.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, этот шаг завершится неудачей, и вам потребуется выполнить некоторые ручные операции.

Дополнительные примеры

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

class RemoveEmptyTags < ActiveRecord::Migration[6.0]
  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[6.0]
  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[6.0]
  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[6.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).

Если вы предпочитаете использовать числовые префиксы, вы можете отключить миграции с отметкой времени, установив:

config.active_record.timestamped_migrations = false

В файле application.rb.

Обратимые миграции

Обратимые миграции — это миграции, которые умеют автоматически выполнять обратную операцию. Вы просто предоставляете логику up, а система Migration определяет, как выполнить команды отката для вас.

Для определения обратимой миграции, определите метод change в вашей миграции так:

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

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

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