Parent

Files

Class Index [+]

Quicksearch

ActiveRecord::Migration

Active Record Migrations

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

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

  rails generate migration MyNewMigration

where MyNewMigration is the name of your migration. The generator will create an empty migration file timestamp_my_new_migration.rb in the db/migrate/ directory where timestamp is the UTC formatted date and time that the migration was generated.

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.

  rails generate migration add_fieldname_to_tablename fieldname:string

This will generate the file timestamp_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 application.rb.

Public Class Methods

announce(message) click to toggle source
     # File lib/active_record/migration.rb, line 344
344:       def announce(message)
345:         version = defined?(@version) ? @version : nil
346: 
347:         text = "#{version} #{name}: #{message}"
348:         length = [0, 75 - text.length].max
349:         write "== %s %s" % [text, "=" * length]
350:       end
connection() click to toggle source
     # File lib/active_record/migration.rb, line 372
372:       def connection
373:         ActiveRecord::Base.connection
374:       end
method_missing(method, *arguments, &block) click to toggle source
     # File lib/active_record/migration.rb, line 376
376:       def method_missing(method, *arguments, &block)
377:         arg_list = arguments.map{ |a| a.inspect } * ', '
378: 
379:         say_with_time "#{method}(#{arg_list})" do
380:           unless arguments.empty? || method == :execute
381:             arguments[0] = Migrator.proper_table_name(arguments.first)
382:           end
383:           connection.send(method, *arguments, &block)
384:         end
385:       end
migrate(direction) click to toggle source

Execute this migration in the named direction

     # File lib/active_record/migration.rb, line 303
303:       def migrate(direction)
304:         return unless respond_to?(direction)
305: 
306:         case direction
307:           when :up   then announce "migrating"
308:           when :down then announce "reverting"
309:         end
310: 
311:         result = nil
312:         time = Benchmark.measure { result = send("#{direction}_without_benchmarks") }
313: 
314:         case direction
315:           when :up   then announce "migrated (%.4fs)" % time.real; write
316:           when :down then announce "reverted (%.4fs)" % time.real; write
317:         end
318: 
319:         result
320:       end
say(message, subitem=false) click to toggle source
     # File lib/active_record/migration.rb, line 352
352:       def say(message, subitem=false)
353:         write "#{subitem ? "   ->" : "--"} #{message}"
354:       end
say_with_time(message) click to toggle source
     # File lib/active_record/migration.rb, line 356
356:       def say_with_time(message)
357:         say(message)
358:         result = nil
359:         time = Benchmark.measure { result = yield }
360:         say "%.4fs" % time.real, :subitem
361:         say("#{result} rows", :subitem) if result.is_a?(Integer)
362:         result
363:       end
suppress_messages() click to toggle source
     # File lib/active_record/migration.rb, line 365
365:       def suppress_messages
366:         save, self.verbose = verbose, false
367:         yield
368:       ensure
369:         self.verbose = save
370:       end
write(text="") click to toggle source
     # File lib/active_record/migration.rb, line 340
340:       def write(text="")
341:         puts(text) if verbose
342:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.