ActiveRecord::Migration

Migrations can manage the evolution of a schema used by several physical databases. It’s a solution to the common problem of adding a field to make a new feature work in your local database, but being unsure of how to push that change to other developers and to the production server. With migrations, you can describe the transformations in self-contained classes that can be checked into version control systems and executed against another database that might be one, two, or five versions behind.

Example of a simple migration:

  class AddSsl < ActiveRecord::Migration
    def self.up
      add_column :accounts, :ssl_enabled, :boolean, :default => 1
    end

    def self.down
      remove_column :accounts, :ssl_enabled
    end
  end

This migration will add a boolean flag to the accounts table and remove it again, if you’re backing out of the migration. It shows how all migrations have two class methods up and down that describes the transformations required to implement or remove the migration. These methods can consist of both the migration specific methods, like add_column and remove_column, but may also contain regular Ruby code for generating data needed for the transformations.

Example of a more complex migration that also needs to initialize data:

  class AddSystemSettings < ActiveRecord::Migration
    def self.up
      create_table :system_settings do |t|
        t.column :name,     :string
        t.column :label,    :string
        t.column :value,    :text
        t.column :type,     :string
        t.column :position, :integer
      end

      SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1
    end

    def self.down
      drop_table :system_settings
    end
  end

This migration first adds the system_settings table, then creates the very first row in it using the Active Record model that relies on the table. It also uses the more advanced create_table syntax where you can specify a complete table schema in one block call.

Available transformations

• create_table(name, options) Creates a table called name and makes the table object available to a block that can then add columns to it, following the same format as add_column. See example above. The options hash is for fragments like "DEFAULT CHARSET=UTF-8" that are appended to the create table definition.
• drop_table(name): Drops the table called name.
• add_column(table_name, column_name, type, options): Adds a new column to the table called table_name named column_name specified to be one of the following types: :string, :text, :integer, :float, :datetime, :timestamp, :time, :date, :binary, :boolean. A default value can be specified by passing an options hash like { :default => 11 }.
• rename_column(table_name, column_name, new_column_name): Renames a column but keeps the type and content.
• change_column(table_name, column_name, type, options): Changes the column to a different type using the same parameters as add_column.
• remove_column(table_name, column_name): Removes the column named column_name from the table called table_name.
• add_index(table_name, column_name, index_type): Add a new index with the name of the column on the column. Specify an optional index_type (e.g. UNIQUE).
• remove_index(table_name, column_name): Remove the index called the same as the column.

Irreversible transformations

Some transformations are destructive in a manner that cannot be reversed. Migrations of that kind should raise an IrreversibleMigration exception in their down method.

Running migrations from within Rails

The <a href="/rails/Rails">Rails</a> package has several tools to help create and apply migrations.

To generate a new migration, use script/generate migration MyNewMigration where MyNewMigration is the name of your migration. The generator will create a file nnn_my_new_migration.rb in the db/migrate/ directory, where nnn is the next largest migration number. You may then edit the self.up and self.down methods of n MyNewMigration.

To run migrations against the currently configured database, use rake migrate. This will update the database by running all of the pending migrations, creating the schema_info table if missing.

To roll the database back to a previous migration version, use rake migrate version=X where X is the version to which you wish to downgrade. If any of the migrations throw an IrreversibleMigration exception, that step will fail and you’ll have some manual work to do.

Database support

Migrations are currently supported in MySQL, PostgreSQL, SQLite, SQL Server, and Oracle (all supported databases except DB2).

More examples

Not all migrations change the schema. Some just fix the data:

  class RemoveEmptyTags < ActiveRecord::Migration
    def self.up
      Tag.find(:all).each { |tag| tag.destroy if tag.pages.empty? }
    end

    def self.down
      # not much we can do to restore deleted data
      raise IrreversibleMigration
    end
  end

Others remove columns when they migrate up instead of down:

  class RemoveUnnecessaryItemAttributes < ActiveRecord::Migration
    def self.up
      remove_column :items, :incomplete_items_count
      remove_column :items, :completed_items_count
    end

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

And sometimes you need to do something in SQL not abstracted directly by migrations:

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

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

Using a model after changing its table

Sometimes you’ll want to add a column in a migration and populate it immediately after. In that case, you’ll need to make a call to Base#reset_column_information in order to ensure that the model has the latest column data from after the new column was added. Example:

  class AddPeopleSalary < ActiveRecord::Migration
    def self.up
      add_column :people, :salary, :integer
      Person.reset_column_information
      Person.find(:all).each do |p|
        p.salary = SalaryCalculator.compute(p)
      end
    end
  end

class ActiveRecord::Migration
def self.load_data(filename, dir = 'db/migrate/data')
  Fixtures.create_fixtures(File.join(RAILS_ROOT, dir), filename)
end
end

class CreateCountries < ActiveRecord::Migration
def self.up
  create_table :countries do |t|
    t.string :name, :code, :null => false
    t.timestamps
  end
  load_data :countries
end

def self.down
  drop_table :countries
end
end

require 'create_ex_girl_friend_texts' # the migration file

class AddCurrentToVendor < ActiveRecord::Migration

class Vendor < ActiveRecord::Base
end

class Article < ActiveRecord::Base
  has_many :vendors, :class_name => 'AddCurrentToVendor::Vendor', :order => 'created_at'
end

def self.up
  add_column :vendors, :current, :boolean
  Article.all.each do |article|
    article.vendors.first.andand.update_attribute(:current, true)
  end
end

def self.down
  remove_column :vendors, :current
end
end

class AddUniquenessBarToFoo < ActiveRecord::Migration
class Foo < ActiveRecord::Base
end

def change

  add_column :foos, :bar, :string
  execute "ALTER TABLE foos ADD CONSTRAINT uk_foods_bar UNIQUE (bar)"    

  Foo.reset_column_information
  Foo.all.each do |f|
    begin
      #try get unique value in a new sub-transaction
      Foo.transaction(requires_new: true) do
        f.update_attributes!(:bar => "some ops. with another non-unique existent field to set this")
      end
    rescue ActiveRecord::StatementInvalid
       #We can't reuse a crashed transaction. New one.
       Foo.transaction(requires_new: true) do
        #Alternative unique value, if another error exist it's another
        #migration problem and then raise new error.
        f.update_attributes!(:bar => "some operation to set this-#{f.id}")
      end
    end
  end   
  change_column :foos, :bar, :string, :null => false

end
end