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.
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
.
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.
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.
Migrations are currently supported in MySQL, PostgreSQL, SQLite, SQL Server, Sybase, and Oracle (all supported databases except DB2).
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
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
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.
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.
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.
# File lib/active_record/migration.rb, line 346 def announce(message) version = defined?(@version) ? @version : nil text = "#{version} #{name}: #{message}" length = [0, 75 - text.length].max write "== %s %s" % [text, "=" * length] end
# File lib/active_record/migration.rb, line 374 def connection ActiveRecord::Base.connection end
# File lib/active_record/migration.rb, line 378 def method_missing(method, *arguments, &block) arg_list = arguments.map{ |a| a.inspect } * ', ' say_with_time "#{method}(#{arg_list})" do unless arguments.empty? || method == :execute arguments[0] = Migrator.proper_table_name(arguments.first) end connection.send(method, *arguments, &block) end end
Execute this migration in the named direction
# File lib/active_record/migration.rb, line 305 def migrate(direction) return unless respond_to?(direction) case direction when :up then announce "migrating" when :down then announce "reverting" end result = nil time = Benchmark.measure { result = send("#{direction}_without_benchmarks") } case direction when :up then announce "migrated (%.4fs)" % time.real; write when :down then announce "reverted (%.4fs)" % time.real; write end result end
# File lib/active_record/migration.rb, line 354 def say(message, subitem=false) write "#{subitem ? " ->" : "--"} #{message}" end
# File lib/active_record/migration.rb, line 358 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
# File lib/active_record/migration.rb, line 367 def suppress_messages save, self.verbose = verbose, false yield ensure self.verbose = save end
# File lib/active_record/migration.rb, line 342 def write(text="") puts(text) if verbose end