Flowdock

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 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.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 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.
  • rename_table(old_name, new_name): Renames the table called old_name to new_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, :decimal, :datetime, :timestamp, :time, :date, :binary, :boolean. A default value can be specified by passing an options hash like { :default => 11 }. Other options include :limit and :null (e.g. { :limit => 50, :null => false }) — see ActiveRecord::ConnectionAdapters::TableDefinition#column for details.
  • 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_names, options): Adds a new index with the name of the column. Other options include :name and :unique (e.g. { :name => "users_name_index", :unique => true }).
  • remove_index(table_name, index_name): Removes the index specified by index_name.

Irreversible transformations

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

Running migrations from within Rails

The Rails package has several tools to help create and apply migrations.

To generate a new migration, you can use

  script/generate migration MyNewMigration

where MyNewMigration is the name of your migration. The generator will create an empty migration 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 MyNewMigration.

There is a special syntactic shortcut to generate migrations that add fields to a table.

  script/generate migration add_fieldname_to_tablename fieldname:string

This will generate the file nnn_add_fieldname_to_tablename, which will look like this:

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

    def self.down
      remove_column :tablenames, :fieldname
    end
  end

To run migrations against the currently configured database, use rake db:migrate. This will update the database by running all of the pending migrations, creating the schema_migrations table (see "About the schema_migrations table" section below) if missing. It will also invoke the db:schema:dump task, which will update your db/schema.rb file to match the structure of your database.

To roll the database back to a previous migration version, use rake db:migrate VERSION=X where X is the version to which you wish to downgrade. If any of the migrations throw an ActiveRecord::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, Sybase, 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 ActiveRecord::IrreversibleMigration, "Can't recover the deleted tags"
    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.update_attribute :salary, SalaryCalculator.compute(p)
      end
    end
  end

Controlling verbosity

By default, migrations will describe the actions they are taking, writing them to the console as they happen, along with benchmarks describing how long each step took.

You can quiet them down by setting ActiveRecord::Migration.verbose = false.

You can also insert your own messages and benchmarks by using the say_with_time method:

  def self.up
    ...
    say_with_time "Updating salaries..." do
      Person.find(:all).each do |p|
        p.update_attribute :salary, SalaryCalculator.compute(p)
      end
    end
    ...
  end

The phrase "Updating salaries…" would then be printed, along with the benchmark for the block when the block completes.

About the schema_migrations table

Rails versions 2.0 and prior used to create a table called schema_info when using migrations. This table contained the version of the schema as of the last applied migration.

Starting with Rails 2.1, the schema_info table is (automatically) replaced by the schema_migrations table, which contains the version numbers of all the migrations applied.

As a result, it is now possible to add migration files that are numbered lower than the current schema version: when migrating up, those never-applied "interleaved" migrations will be automatically applied, and when migrating down, never-applied "interleaved" migrations will be skipped.

Timestamped Migrations

By default, Rails generates migrations that look like:

   20080717013526_your_migration_name.rb

The prefix is a generation timestamp (in UTC).

If you’d prefer to use numeric prefixes, you can turn timestamped migrations off by setting:

   config.active_record.timestamped_migrations = false

In environment.rb.

Show files where this class is defined (1 file)
Register or log in to add new notes.
July 22, 2008 - (>= v2.1.0)
11 thanks

Migration helpers

You can add your own migration helpers as references:

Code example

class ActiveRecord::ConnectionsAdapters::TableDefinition
  def counter_caches(*args)
    args.each { |col| column("#{col}_count", :integer, :default => 0) }
  end
end

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      t.string :first_name, :last_name, :email
      t.counter_caches :photos, :messages
      t.timestamps
    end
  end

  def self.down
    drop_table :users
  end
end
July 23, 2008
6 thanks

Loading fixtures in migrations

This helper is wrapper around Fixtures#create_fixtures and just load fixtures from specified directory (db/migrate/data by default):

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

It is usefull for tables with data like country list:

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
December 11, 2008 - (>= v1.0.0)
5 thanks

Calling migrations within migrations

It’s very occasionally a wise strategy to call migrations from within other migrations. This is typically done when you are adding a migration that deletes a now-obsolete table.

Let’s say one night when you were drunk or otherwise not thinking straight you did something like this:

class CreateExGirlfriendTexts < ActiveRecord::Migration
  def self(dot)up
    create_table :ex_girlfriend_texts { |t| ... }
  end

  def self(dot)down
    drop_table :ex_girlfriend_texts
  end
end

Oops! You could add this for your “undo” migration the next morning:

class FixDrunkMistake < ActiveRecord::Migration
  def self(dot)up
    CreateExGirlfriendTexts.down
  end

  def self(dot)down
    CreateExGirlfriendTexts.up
  end
end

Now, in the event you decide you really did like that table, you can always get it back easily. Keep in mind this will be made more complicated if your table is modified over multiple transactions.

July 22, 2008 - (v2.1.0)
4 thanks

Rails 2.1 migrations

Things to take note of are the lack of ‘column spam’, which didn’t convey much semantic meaning. Also the combination of multiple fields per line with the same type.

references is also a nice helper to convey relationship information (t.references :role is equivilant to t.integer :role_id). references also takes another parameters, see the method for more details.

code

class CreateUsers < ActiveRecord::Migration
  def self.up
    create_table :users do |t|
      t.string :first_name, :last_name, :email
      t.text :address
      t.date :date_of_birth
      t.references :role

      t.timestamps
    end

    add_index :users, :email
  end

  def self.down
    drop_table :users
  end
end
October 22, 2008 - (>= v2.1.0)
2 thanks

HABTM relation

When you want to create a has_and_belong_to_many relation (og just a has_many :through) use this setup.

Example
class CreateCourses < ActiveRecord::Migration
  def self.up
    create_table :seasons do |t|
      t.integer :year
      t.string :period
    end

    create_table :courses do |t|
      t.string :courseCode
    end

    create_table :courses_seasons, :id => false do |t|
      t.references :course, :null => false
      t.references :season, :null => false
    end
    add_index :courses_seasons, [:course_id, :season_id], :unique => true

  end

  def self.down
    drop_table :seasons
    drop_table :courses
    drop_table :courses_seasons
  end
end
December 6, 2013
0 thanks

Update the uniqueness field when it value dependent on another existent field without uniqueness restriction.

I’m using sub-transaction to update existent records on DB. I use this approach to update the uniqueness field when it value dependent on another existent field without uniqueness restriction.

Migration for uniqueness with existent dependent data in DB

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

Be aware about performance that is transaction per record for big DB.

November 11, 2009
0 thanks

Calling migrations within migrations observation

Following the advice from RISCfuture I could not call a migration from within another migration. I got the following errror message:

NameError Exception: uninitialized constant FixDrunkMistake::CreateExGirlfriendTexts.down

Only after I did a

require 'create_ex_girl_friend_texts' # the migration file

before the migration call did everything work as expected.

March 25, 2010
0 thanks

Using models in your migration

Here is some advice how to call your models in a migration without shooting yourself in the foot:

http://gem-session.com/2010/03/how-to-use-models-in-your-migrations-without-killing-kittens

Basically you can inline models into your migrations to decouple them from changes in your model:

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
June 13, 2010 - (>= v2.3.8)
0 thanks

Positioning the column. MySQL only

Add support for MySQL column positioning via #add_column and #change_column

add_column and change_column in the MySQL adapter now accept some additional options:

:first => true # Put the column in front of all the columns

:after => column_name # Put the column after ‘column_name’

class AddLastNameToUsers < ActiveRecord::Migration
  def self.up
    add_column :users, :last_name, :after => :first_name
  end

  def self.down
    remove_column :users, :last_name
  end
end

or

class AddIdToUsers < ActiveRecord::Migration
  def self.up
    add_column :urers, :id, :first => true
  end

  def self.down
    remove_column :users, :id
  end
end