Flowdock

Not found

The exact documentation you were looking for could not be found. Here is the best guess.

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[6.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[6.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, to_table = nil, **options): 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

bin/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.

bin/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[6.0]
  def change
    add_column :tablenames, :fieldname, :string
  end
end

To run migrations against the currently configured database, use bin/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 command, 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 bin/rails db:rollback 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. bin/rails db:rollback 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.

More examples

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

class RemoveEmptyTags < ActiveRecord::Migration[6.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[6.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[6.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[6.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[6.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 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[6.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!.

Constants

ReversibleBlockHelper = Struct.new(:reverting) do #:nodoc: def up yield unless reverting end def down yield if reverting end end

MigrationFilenameRegexp = /\A([0-9]+)_([_a-z0-9]*)\.?([_a-z0-9]*)?\.rb\z/

Attributes

[RW] version
[RW] name
[RW] disable_ddl_transaction
[RW] delegate
Show files where this class is defined (4 files)
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