Class: ActiveRecord::Migration

Inherits:
Object
  • Object
show all
Defined in:
lib/active_record/migration.rb,
lib/active_record/migration/join_table.rb,
lib/active_record/migration/command_recorder.rb

Overview

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 up
    add_column :accounts, :ssl_enabled, :boolean, default: true
  end

  def 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 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 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

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.

  • change_table(name, options): Allows to make column alterations to the table called name. It makes the table object available to a block that can then add/remove columns, indexes or foreign keys to it.

  • 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, type, options): 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, :unique (e.g. { name: 'users_name_index', unique: true }) and :order (e.g. { order: { name: :desc } }).

  • remove_index(table_name, column: column_name): Removes the index specified by column_name.

  • remove_index(table_name, 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

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 up and 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 up
    add_column :tablenames, :fieldname, :string
  end

  def 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 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

Others remove columns when they migrate up instead of down:

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

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

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

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

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 up
  ...
  say_with_time "Updating salaries..." do
    Person.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.

Reversible Migrations

Starting with Rails 3.1, you will be able to define reversible migrations. Reversible migrations are migrations that know how to go down for you. You simply supply the up logic, and the Migration system will figure out how to execute the down commands for you.

To define a reversible migration, define the change method in your migration like this:

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

This migration will create the horses table for you on the way up, and automatically figure out how to drop the table on the way down.

Some commands like remove_column cannot be reversed. If you care to define how to move up and down in these cases, you should define the up and down methods as before.

If a command cannot be reversed, an ActiveRecord::IrreversibleMigration exception will be raised when the migration is moving down.

For a list of commands that are reversible, please see ActiveRecord::Migration::CommandRecorder.

Transactional Migrations

If the database adapter supports DDL transactions, all migrations will automatically be wrapped in a transaction. There are queries that you can’t execute inside a transaction though, and for these situations you can turn the automatic transactions off.

class ChangeEnum < ActiveRecord::Migration
  disable_ddl_transaction!

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

Remember that you can still open your own transactions, even if you are in a Migration with self.disable_ddl_transaction!.

Direct Known Subclasses

Schema

Defined Under Namespace

Modules: JoinTable Classes: CheckPending, CommandRecorder, ReversibleBlockHelper

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name = self.class.name, version = nil) ⇒ Migration

Returns a new instance of Migration.



406
407
408
409
410
 
# File 'lib/active_record/migration.rb', line 406

def initialize(name = self.class.name, version = nil)
  @name       = name
  @version    = version
  @connection = nil
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method, *arguments, &block) ⇒ Object 



618
619
620
621
622
623
624
625
626
627
628
629
630
631
 
# File 'lib/active_record/migration.rb', line 618

def method_missing(method, *arguments, &block)
  arg_list = arguments.map{ |a| a.inspect } * ', '

  say_with_time "#{method}(#{arg_list})" do
    unless @connection.respond_to? :revert
      unless arguments.empty? || method == :execute
        arguments[0] = Migrator.proper_table_name(arguments.first)
        arguments[1] = Migrator.proper_table_name(arguments.second) if method == :rename_table
      end
    end
    return super unless connection.respond_to?(method)
    connection.send(method, *arguments, &block)
  end
end

Class Attribute Details

.delegate ⇒ Object

:nodoc:



378
379
380
 
# File 'lib/active_record/migration.rb', line 378

def delegate
  @delegate
end

.disable_ddl_transaction ⇒ Object

:nodoc:



379
380
381
 
# File 'lib/active_record/migration.rb', line 379

def disable_ddl_transaction
  @disable_ddl_transaction
end

Instance Attribute Details

#name ⇒ Object

Returns the value of attribute name.



404
405
406
 
# File 'lib/active_record/migration.rb', line 404

def name
  @name
end

#version ⇒ Object

Returns the value of attribute version.



404
405
406
 
# File 'lib/active_record/migration.rb', line 404

def version
  @version
end

Class Method Details

.check_pending! ⇒ Object

Raises:



382
383
384
 
# File 'lib/active_record/migration.rb', line 382

def self.check_pending!
  raise ActiveRecord::PendingMigrationError if ActiveRecord::Migrator.needs_migration?
end

.disable_ddl_transaction! ⇒ Object

Disable DDL transactions for this migration.



395
396
397
 
# File 'lib/active_record/migration.rb', line 395

def self.disable_ddl_transaction!
  @disable_ddl_transaction = true
end

.method_missing(name, *args, &block) ⇒ Object

:nodoc:



386
387
388
 
# File 'lib/active_record/migration.rb', line 386

def self.method_missing(name, *args, &block) # :nodoc:
  (delegate || superclass.delegate).send(name, *args, &block)
end

.migrate(direction) ⇒ Object 



390
391
392
 
# File 'lib/active_record/migration.rb', line 390

def self.migrate(direction)
  new.migrate direction
end

Instance Method Details

#announce(message) ⇒ Object 



588
589
590
591
592
 
# File 'lib/active_record/migration.rb', line 588

def announce(message)
  text = "#{version} #{name}: #{message}"
  length = [0, 75 - text.length].max
  write "== %s %s" % [text, "=" * length]
end

#connection ⇒ Object 



614
615
616
 
# File 'lib/active_record/migration.rb', line 614

def connection
  @connection || ActiveRecord::Base.connection
end

#copy(destination, sources, options = {}) ⇒ Object 



633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
 
# File 'lib/active_record/migration.rb', line 633

def copy(destination, sources, options = {})
  copied = []

  FileUtils.mkdir_p(destination) unless File.exist?(destination)

  destination_migrations = ActiveRecord::Migrator.migrations(destination)
  last = destination_migrations.last
  sources.each do |scope, path|
    source_migrations = ActiveRecord::Migrator.migrations(path)

    source_migrations.each do |migration|
      source = File.binread(migration.filename)
      inserted_comment = "# This migration comes from #{scope} (originally #{migration.version})\n"
      if /\A#.*\b(?:en)?coding:\s*\S+/ =~ source
        # If we have a magic comment in the original migration,
        # insert our comment after the first newline(end of the magic comment line)
        # so the magic keep working.
        # Note that magic comments must be at the first line(except sh-bang).
        source[/\n/] = "\n#{inserted_comment}"
      else
        source = "#{inserted_comment}#{source}"
      end

      if duplicate = destination_migrations.detect { |m| m.name == migration.name }
        if options[:on_skip] && duplicate.scope != scope.to_s
          options[:on_skip].call(scope, migration)
        end
        next
      end

      migration.version = next_migration_number(last ? last.version + 1 : 0).to_i
      new_path = File.join(destination, "#{migration.version}_#{migration.name.underscore}.#{scope}.rb")
      old_path, migration.filename = migration.filename, new_path
      last = migration

      File.binwrite(migration.filename, source)
      copied << migration
      options[:on_copy].call(scope, migration, old_path) if options[:on_copy]
      destination_migrations << migration
    end
  end

  copied
end

#disable_ddl_transaction ⇒ Object

:nodoc:



399
400
401
 
# File 'lib/active_record/migration.rb', line 399

def disable_ddl_transaction # :nodoc:
  self.class.disable_ddl_transaction
end

#down ⇒ Object 



541
542
543
544
545
 
# File 'lib/active_record/migration.rb', line 541

def down
  self.class.delegate = self
  return unless self.class.respond_to?(:down)
  self.class.down
end

#exec_migration(conn, direction) ⇒ Object 



569
570
571
572
573
574
575
576
577
578
579
580
581
582
 
# File 'lib/active_record/migration.rb', line 569

def exec_migration(conn, direction)
  @connection = conn
  if respond_to?(:change)
    if direction == :down
      revert { change }
    else
      change
    end
  else
    send(direction)
  end
ensure
  @connection = nil
end

#migrate(direction) ⇒ Object

Execute this migration in the named direction



548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
 
# File 'lib/active_record/migration.rb', line 548

def migrate(direction)
  return unless respond_to?(direction)

  case direction
  when :up   then announce "migrating"
  when :down then announce "reverting"
  end

  time   = nil
  ActiveRecord::Base.connection_pool.with_connection do |conn|
    time = Benchmark.measure do
      exec_migration(conn, direction)
    end
  end

  case direction
  when :up   then announce "migrated (%.4fs)" % time.real; write
  when :down then announce "reverted (%.4fs)" % time.real; write
  end
end

#next_migration_number(number) ⇒ Object 



678
679
680
681
682
683
684
 
# File 'lib/active_record/migration.rb', line 678

def next_migration_number(number)
  if ActiveRecord::Base.timestamped_migrations
    [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % number].max
  else
    "%.3d" % number
  end
end

#reversible ⇒ Object

Used to specify an operation that can be run in one direction or another. Call the methods up and down of the yielded object to run a block only in one given direction. The whole block will be called in the right order within the migration.

In the following example, the looping on users will always be done when the three columns ‘first_name’, ‘last_name’ and ‘full_name’ exist, even when migrating down:

class SplitNameMigration < ActiveRecord::Migration
  def change
    add_column :users, :first_name, :string
    add_column :users, :last_name, :string

    reversible do |dir|
      User.reset_column_information
      User.all.each do |u|
        dir.up   { u.first_name, u.last_name = u.full_name.split(' ') }
        dir.down { u.full_name = "#{u.first_name} #{u.last_name}" }
        u.save
      end
    end

    revert { add_column :users, :full_name, :string }
  end
end



512
513
514
515
 
# File 'lib/active_record/migration.rb', line 512

def reversible
  helper = ReversibleBlockHelper.new(reverting?)
  execute_block{ yield helper }
end

#revert(*migration_classes) ⇒ Object

Reverses the migration commands for the given block and the given migrations.

The following migration will remove the table ‘horses’ and create the table ‘apples’ on the way up, and the reverse on the way down.

class FixTLMigration < ActiveRecord::Migration
  def change
    revert do
      create_table(:horses) do |t|
        t.text :content
        t.datetime :remind_at
      end
    end
    create_table(:apples) do |t|
      t.string :variety
    end
  end
end

Or equivalently, if TenderloveMigration is defined as in the documentation for Migration:

require_relative '2012121212_tenderlove_migration'

class FixupTLMigration < ActiveRecord::Migration
  def change
    revert TenderloveMigration

    create_table(:apples) do |t|
      t.string :variety
    end
  end
end

This command can be nested.



453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
 
# File 'lib/active_record/migration.rb', line 453

def revert(*migration_classes)
  run(*migration_classes.reverse, revert: true) unless migration_classes.empty?
  if block_given?
    if @connection.respond_to? :revert
      @connection.revert { yield }
    else
      recorder = CommandRecorder.new(@connection)
      @connection = recorder
      suppress_messages do
        @connection.revert { yield }
      end
      @connection = recorder.delegate
      recorder.commands.each do |cmd, args, block|
        send(cmd, *args, &block)
      end
    end
  end
end

#reverting? ⇒ Boolean

Returns:

  • (Boolean) 


472
473
474
 
# File 'lib/active_record/migration.rb', line 472

def reverting?
  @connection.respond_to?(:reverting) && @connection.reverting
end

#run(*migration_classes) ⇒ Object

Runs the given migration classes. Last argument can specify options:

  • :direction (default is :up)

  • :revert (default is false)



521
522
523
524
525
526
527
528
529
530
531
532
533
 
# File 'lib/active_record/migration.rb', line 521

def run(*migration_classes)
  opts = migration_classes.extract_options!
  dir = opts[:direction] || :up
  dir = (dir == :down ? :up : :down) if opts[:revert]
  if reverting?
    # If in revert and going :up, say, we want to execute :down without reverting, so
    revert { run(*migration_classes, direction: dir, revert: true) }
  else
    migration_classes.each do |migration_class|
      migration_class.new.exec_migration(@connection, dir)
    end
  end
end

#say(message, subitem = false) ⇒ Object 



594
595
596
 
# File 'lib/active_record/migration.rb', line 594

def say(message, subitem=false)
  write "#{subitem ? "   ->" : "--"} #{message}"
end

#say_with_time(message) ⇒ Object 



598
599
600
601
602
603
604
605
 
# File 'lib/active_record/migration.rb', line 598

def say_with_time(message)
  say(message)
  result = nil
  time = Benchmark.measure { result = yield }
  say "%.4fs" % time.real, :subitem
  say("#{result} rows", :subitem) if result.is_a?(Integer)
  result
end

#suppress_messages ⇒ Object 



607
608
609
610
611
612
 
# File 'lib/active_record/migration.rb', line 607

def suppress_messages
  save, self.verbose = verbose, false
  yield
ensure
  self.verbose = save
end

#up ⇒ Object 



535
536
537
538
539
 
# File 'lib/active_record/migration.rb', line 535

def up
  self.class.delegate = self
  return unless self.class.respond_to?(:up)
  self.class.up
end

#write(text = "") ⇒ Object 



584
585
586
 
# File 'lib/active_record/migration.rb', line 584

def write(text="")
  puts(text) if verbose
end