# class 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[5.0]
      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[5.0]
      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¶ ↑

### Creation¶ ↑

- `create_join_table(table_1, table_2, options)`: Creates a join table having its name as the lexical order of the first two arguments. See ActiveRecord::ConnectionAdapters::SchemaStatements#create_join_table for details.

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

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

- `add_foreign_key(from_table, to_table, options)`: Adds a new foreign key. `from_table` is the table with the key column, `to_table` contains the referenced primary key.

- `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 } }`).

- `add_reference(:table_name, :reference_name)`: Adds a new column `reference_name_id` by default an integer. See ActiveRecord::ConnectionAdapters::SchemaStatements#add_reference for details.

- `add_timestamps(table_name, options)`: Adds timestamps (`created_at` and `updated_at`) columns to `table_name`.

### Modification¶ ↑

- `change_column(table_name, column_name, type, options)`: Changes the column to a different type using the same parameters as add_column.

- `change_column_default(table_name, column_name, default_or_changes)`: Sets a default value for `column_name` defined by `default_or_changes` on `table_name`. Passing a hash containing `:from` and `:to` as `default_or_changes` will make this change reversible in the migration.

- `change_column_null(table_name, column_name, null, default = nil)`: Sets or removes a +NOT NULL+ constraint on `column_name`. The `null` flag indicates whether the value can be `NULL`. See ActiveRecord::ConnectionAdapters::SchemaStatements#change_column_null for details.

- `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_column(table_name, column_name, new_column_name)`: Renames a column but keeps the type and content.

- `rename_index(table_name, old_name, new_name)`: Renames an index.

- `rename_table(old_name, new_name)`: Renames the table called `old_name` to `new_name`.

### Deletion¶ ↑

- `drop_table(name)`: Drops the table called `name`.

- `drop_join_table(table_1, table_2, options)`: Drops the join table specified by the given arguments.

- `remove_column(table_name, column_name, type, options)`: Removes the column named `column_name` from the table called `table_name`.

- `remove_columns(table_name, *column_names)`: Removes the given columns from the table definition.

- `remove_foreign_key(from_table, options_or_to_table)`: Removes the given foreign key from the table called `table_name`.

- `remove_index(table_name, column: column_names)`: Removes the index specified by `column_names`.

- `remove_index(table_name, name: index_name)`: Removes the index specified by `index_name`.

- `remove_reference(table_name, ref_name, options)`: Removes the reference(s) on `table_name` specified by `ref_name`.

- `remove_timestamps(table_name, options)`: Removes the timestamp columns (`created_at` and `updated_at`) from the table definition.

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

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.rb`, which will look like this:

    class AddFieldnameToTablename < ActiveRecord::Migration[5.0]
      def change
        add_column :tablenames, :fieldname, :string
      end
    end

To run migrations against the currently configured database, use `rails 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 `rails db:migrate VERSION=X` where `X` is the version to which you wish to downgrade. Alternatively, you can also use the STEP option if you wish to rollback last few migrations. `rails db:migrate STEP=2` will rollback the latest two migrations.

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, and Oracle (all supported databases except DB2).

## More examples¶ ↑

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

    class RemoveEmptyTags < ActiveRecord::Migration[5.0]
      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[5.0]
      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[5.0]
      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[5.0]
      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.

## 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¶ ↑

Reversible migrations are migrations that know how to go `down` for you. You simply supply the `up` logic, and the Migration system figures 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[5.0]
      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[5.0]
      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!`.

### Attributes

name[RW]
version[RW]

### Public Class Methods

[](version) click to toggle source

    # File lib/active_record/migration.rb, line 532
    def self.[](version)
      Compatibility.find(version)
    end

check_pending!(connection = Base.connection) click to toggle source

Raises `ActiveRecord::PendingMigrationError` error if any migrations are pending.

    # File lib/active_record/migration.rb, line 575
    def check_pending!(connection = Base.connection)
      raise ActiveRecord::PendingMigrationError if ActiveRecord::Migrator.needs_migration?(connection)
    end

current_version() click to toggle source

    # File lib/active_record/migration.rb, line 536
    def self.current_version
      ActiveRecord::VERSION::STRING.to_f
    end

disable_ddl_transaction!() click to toggle source

Disable the transaction wrapping this migration. You can still create your own transactions even after calling disable_ddl_transaction!

For more details read the “Transactional Migrations” section above.

    # File lib/active_record/migration.rb, line 611
    def disable_ddl_transaction!
      @disable_ddl_transaction = true
    end

load_schema_if_pending!() click to toggle source

    # File lib/active_record/migration.rb, line 579
    def load_schema_if_pending!
      if ActiveRecord::Migrator.needs_migration? || !ActiveRecord::Migrator.any_migrations?
        # Roundtrip to Rake to allow plugins to hook into database initialization.
        FileUtils.cd Rails.root do
          current_config = Base.connection_config
          Base.clear_all_connections!
          system("bin/rails db:test:prepare")
          # Establish a new connection, the old database may be gone (db:test:prepare uses purge)
          Base.establish_connection(current_config)
        end
        check_pending!
      end
    end

migrate(direction) click to toggle source

    # File lib/active_record/migration.rb, line 603
    def migrate(direction)
      new.migrate direction
    end

new(name = self.class.name, version = nil) click to toggle source

    # File lib/active_record/migration.rb, line 623
    def initialize(name = self.class.name, version = nil)
      @name       = name
      @version    = version
      @connection = nil
    end

### Public Instance Methods

announce(message) click to toggle source

    # File lib/active_record/migration.rb, line 805
    def announce(message)
      text = "#{version} #{name}: #{message}"
      length = [0, 75 - text.length].max
      write "== %s %s" % [text, "=" * length]
    end

connection() click to toggle source

    # File lib/active_record/migration.rb, line 831
    def connection
      @connection || ActiveRecord::Base.connection
    end

copy(destination, sources, options = {}) click to toggle source

    # File lib/active_record/migration.rb, line 853
    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

down() click to toggle source

    # File lib/active_record/migration.rb, line 758
    def down
      self.class.delegate = self
      return unless self.class.respond_to?(:down)
      self.class.down
    end

exec_migration(conn, direction) click to toggle source

    # File lib/active_record/migration.rb, line 786
    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

method_missing(method, *arguments, &block) click to toggle source
Calls superclass method

    # File lib/active_record/migration.rb, line 835
    def method_missing(method, *arguments, &block)
      arg_list = arguments.map(&:inspect) * ", "

      say_with_time "#{method}(#{arg_list})" do
        unless connection.respond_to? :revert
          unless arguments.empty? || [:execute, :enable_extension, :disable_extension].include?(method)
            arguments[0] = proper_table_name(arguments.first, table_name_options)
            if [:rename_table, :add_foreign_key].include?(method) ||
              (method == :remove_foreign_key && !arguments.second.is_a?(Hash))
              arguments[1] = proper_table_name(arguments.second, table_name_options)
            end
          end
        end
        return super unless connection.respond_to?(method)
        connection.send(method, *arguments, &block)
      end
    end

migrate(direction) click to toggle source

Execute this migration in the named direction

    # File lib/active_record/migration.rb, line 765
    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) click to toggle source

Determines the version number of the next migration.

    # File lib/active_record/migration.rb, line 910
    def next_migration_number(number)
      if ActiveRecord::Base.timestamped_migrations
        [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % number].max
      else
        SchemaMigration.normalize_migration_number(number)
      end
    end

proper_table_name(name, options = {}) click to toggle source

Finds the correct table name given an Active Record object. Uses the Active Record object's own table_name, or pre/suffix from the options passed in.

    # File lib/active_record/migration.rb, line 901
    def proper_table_name(name, options = {})
      if name.respond_to? :table_name
        name.table_name
      else
        "#{options[:table_name_prefix]}#{name}#{options[:table_name_suffix]}"
      end
    end

reversible() { |helper| ... } click to toggle source

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[5.0]
      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

    # File lib/active_record/migration.rb, line 729
    def reversible
      helper = ReversibleBlockHelper.new(reverting?)
      execute_block { yield helper }
    end

revert(*migration_classes) { || ... } click to toggle source

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[5.0]
      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 '20121212123456_tenderlove_migration'

    class FixupTLMigration < ActiveRecord::Migration[5.0]
      def change
        revert TenderloveMigration

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

This command can be nested.

    # File lib/active_record/migration.rb, line 670
    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?() click to toggle source

    # File lib/active_record/migration.rb, line 689
    def reverting?
      connection.respond_to?(:reverting) && connection.reverting
    end

run(*migration_classes) click to toggle source

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

- :direction (default is :up)

- :revert (default is false)

    # File lib/active_record/migration.rb, line 738
    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) click to toggle source

    # File lib/active_record/migration.rb, line 811
    def say(message, subitem = false)
      write "#{subitem ? "   ->" : "--"} #{message}"
    end

say_with_time(message) { || ... } click to toggle source

    # File lib/active_record/migration.rb, line 815
    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() { || ... } click to toggle source

    # File lib/active_record/migration.rb, line 824
    def suppress_messages
      save, self.verbose = verbose, false
      yield
    ensure
      self.verbose = save
    end

up() click to toggle source

    # File lib/active_record/migration.rb, line 752
    def up
      self.class.delegate = self
      return unless self.class.respond_to?(:up)
      self.class.up
    end

write(text = "") click to toggle source

    # File lib/active_record/migration.rb, line 801
    def write(text = "")
      puts(text) if verbose
    end

### Private Instance Methods

execute_block() { || ... } click to toggle source
Calls superclass method

    # File lib/active_record/migration.rb, line 928
    def execute_block
      if connection.respond_to? :execute_block
        super # use normal delegation to record the block
      else
        yield
      end
    end