Миграции Active Record

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

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

class AddSsl < ActiveRecord::Migration
  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
  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_table(name, options): Создаёт таблицу под названием name и делает объект таблицы доступным для блока, который может затем добавить столбцы к ней, следуя тому же формату, что и add_column. См. пример выше. Хэш опций предназначен для фрагментов, таких как “DEFAULT CHARSET=UTF-8”, которые добавляются к определению создания таблицы.

• drop_table(name): Удаляет таблицу под названием name.

• change_table(name, options): Позволяет изменять столбцы в таблице под названием name. Это делает объект таблицы доступным для блока, который затем может добавлять/удалять столбцы, индексы или внешние ключи к ней.

• rename_table(old_name, new_name): Переименовывает таблицу под названием old_name в new_name.

• 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.

• rename_column(table_name, column_name, new_column_name): Переименовывает столбец, но сохраняет тип и содержимое.

• change_column(table_name, column_name, type, options): Изменяет столбец на другой тип, используя те же параметры, что и add_column.

• remove_column(table_name, column_name, type, options): Удаляет столбец с именем column_name из таблицы под названием table_name.

• add_index(table_name, column_names, options): Добавляет новый индекс с именем столбца. Другие параметры включают :name, :unique (например, { name: 'users_name_index', unique: true } ) и :order (например, { order: { name: :desc } }).

• remove_index(table_name, column: column_name): Удаляет индекс, указанный в column_name.

• remove_index(table_name, name: index_name): Удаляет индекс, указанный в index_name.

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

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

Выполнение миграций из Rails

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

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

rails generate migration MyNewMigration

где MyNewMigration — это имя вашей миграции. Генератор создаст пустой файл миграции timestamp_my_new_migration.rb в каталоге db/migrate/, где timestamp — это отформатированная в формате UTC дата и время генерации миграции.

Затем вы можете отредактировать методы up и down миграции MyNewMigration.

Есть специальное синтаксическое сокращение для генерации миграций, которые добавляют поля в таблицу.

rails generate migration add_fieldname_to_tablename fieldname:string

Это сгенерирует файл timestamp_add_fieldname_to_tablename, который будет выглядеть так:

class AddFieldnameToTablename < ActiveRecord::Migration
  def up
    add_column :tablenames, :fieldname, :string
  end

  def down
    remove_column :tablenames, :fieldname
  end
end

Чтобы запустить миграции против текущей базы данных, используйте rake db:migrate. Это обновит базу данных, выполнив все ожидающие миграции, создав таблицу schema_migrations (см. раздел «О таблице schema_migrations» ниже), если она отсутствует. Это также вызовет задачу db:schema:dump, которая обновит файл db/schema.rb для соответствия структуре вашей базы данных.

Чтобы откатить базу данных до предыдущей версии миграции, используйте rake db:migrate VERSION=X , где X — это версия, к которой вы хотите выполнить откат. Если какая-либо из миграций вызовет исключение ActiveRecord::IrreversibleMigration, эта операция завершится ошибкой, и вам придётся выполнить некоторые ручные действия.

Поддержка баз данных

Миграции в настоящее время поддерживаются в MySQL, PostgreSQL, SQLite, SQL Server, Sybase и Oracle (все поддерживаемые базы данных, кроме DB2).

Больше примеров

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

class RemoveEmptyTags < ActiveRecord::Migration
  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
  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
  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
  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

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

О таблице schema_migrations

Версии Rails 2.0 и более ранние использовали таблицу с именем schema_info при использовании миграций. Эта таблица содержала версию схемы по состоянию на последнюю применённую миграцию.

Начиная с Rails 2.1, таблица schema_info (автоматически) заменяется таблицей schema_migrations, которая содержит номера версий всех применённых миграций.

В результате теперь можно добавлять файлы миграций с номерами, меньшими, чем текущая версия схемы: при миграции вверх эти «вставленные» миграции, которые ещё не были применены, будут автоматически применены, а при миграции вниз «вставленные» миграции, которые ещё не были применены, будут пропущены.

Миграции со временем

По умолчанию Rails генерирует миграции, которые выглядят так:

20080717013526_your_migration_name.rb

Префикс — это временная метка генерации (в формате UTC).

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

config.active_record.timestamped_migrations = false

В файле application.rb.

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

Начиная с Rails 3.1, вы сможете определять обратимые миграции. Обратимые миграции — это миграции, которые знают, как down за вас. Вам просто нужно предоставить логику up, и система миграций выяснит, как выполнить команды обратного перемещения за вас.

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

class TenderloveMigration < ActiveRecord::Migration
  def change
    create_table(:horses) do |t|
      t.column :content, :text
      t.column :remind_at, :datetime
    end
  end
end

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

Некоторые команды, такие как remove_column , не могут быть отменены. Если вам нужно определить, как переходить вверх и вниз в этих случаях, вы должны определять методы up и down как и прежде.

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

Список команд, которые могут быть отменены, см. в ActiveRecord::Migration::CommandRecorder.

Транзакционные миграции

Если адаптер базы данных поддерживает транзакции DDL, все миграции будут автоматически заключены в транзакцию. Однако есть запросы, которые нельзя выполнить внутри транзакции, и для таких ситуаций можно отключить автоматические транзакции.

class ChangeEnum < ActiveRecord::Migration
  disable_ddl_transaction!

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

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