Class: ActiveRecord::Migration
- Inherits:
-
Object
- Object
- ActiveRecord::Migration
- Defined in:
- lib/active_record/migration.rb
Overview
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
-
create_table(name, options)
Creates a table calledname
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 calledname
. -
rename_table(old_name, new_name)
: Renames the table calledold_name
tonew_name
. -
add_column(table_name, column_name, type, options)
: Adds a new column to the table calledtable_name
namedcolumn_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 anoptions
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 namedcolumn_name
from the table calledtable_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 byindex_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
script/generate migration MyNewMigration
where MyNewMigration is the name of your migration. The generator will create an empty migration file nnn_my_new_migration.rb
in the db/migrate/
directory where nnn
is the next largest migration number.
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.
script/generate migration add_fieldname_to_tablename fieldname:string
This will generate the file nnn_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.
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. = false
In environment.rb.
Direct Known Subclasses
Constant Summary collapse
- @@verbose =
true
Class Method Summary collapse
- .announce(message) ⇒ Object
-
.down_with_benchmarks ⇒ Object
:nodoc:.
- .method_missing(method, *arguments, &block) ⇒ Object
-
.migrate(direction) ⇒ Object
Execute this migration in the named direction.
- .say(message, subitem = false) ⇒ Object
- .say_with_time(message) ⇒ Object
-
.singleton_method_added(sym) ⇒ Object
Because the method added may do an alias_method, it can be invoked recursively.
- .suppress_messages ⇒ Object
-
.up_with_benchmarks ⇒ Object
:nodoc:.
- .write(text = "") ⇒ Object
Class Method Details
.announce(message) ⇒ Object
313 314 315 316 317 |
# File 'lib/active_record/migration.rb', line 313 def announce() text = "#{@version} #{name}: #{}" length = [0, 75 - text.length].max write "== %s %s" % [text, "=" * length] end |
.down_with_benchmarks ⇒ Object
:nodoc:
266 267 268 |
# File 'lib/active_record/migration.rb', line 266 def down_with_benchmarks #:nodoc: migrate(:down) end |
.method_missing(method, *arguments, &block) ⇒ Object
339 340 341 342 343 344 345 346 347 348 |
# File 'lib/active_record/migration.rb', line 339 def method_missing(method, *arguments, &block) arg_list = arguments.map(&:inspect) * ', ' say_with_time "#{method}(#{arg_list})" do unless arguments.empty? || method == :execute arguments[0] = Migrator.proper_table_name(arguments.first) end ActiveRecord::Base.connection.send(method, *arguments, &block) end end |
.migrate(direction) ⇒ Object
Execute this migration in the named direction
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 |
# File 'lib/active_record/migration.rb', line 271 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 |
.say(message, subitem = false) ⇒ Object
319 320 321 |
# File 'lib/active_record/migration.rb', line 319 def say(, subitem=false) write "#{subitem ? " ->" : "--"} #{}" end |
.say_with_time(message) ⇒ Object
323 324 325 326 327 328 329 330 |
# File 'lib/active_record/migration.rb', line 323 def say_with_time() say() result = nil time = Benchmark.measure { result = yield } say "%.4fs" % time.real, :subitem say("#{result} rows", :subitem) if result.is_a?(Integer) result end |
.singleton_method_added(sym) ⇒ Object
Because the method added may do an alias_method, it can be invoked recursively. We use @ignore_new_methods as a guard to indicate whether it is safe for the call to proceed.
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 |
# File 'lib/active_record/migration.rb', line 293 def singleton_method_added(sym) #:nodoc: return if defined?(@ignore_new_methods) && @ignore_new_methods begin @ignore_new_methods = true case sym when :up, :down klass = (class << self; self; end) klass.send(:alias_method_chain, sym, "benchmarks") end ensure @ignore_new_methods = false end end |
.suppress_messages ⇒ Object
332 333 334 335 336 337 |
# File 'lib/active_record/migration.rb', line 332 def save, self.verbose = verbose, false yield ensure self.verbose = save end |
.up_with_benchmarks ⇒ Object
:nodoc:
262 263 264 |
# File 'lib/active_record/migration.rb', line 262 def up_with_benchmarks #:nodoc: migrate(:up) end |
.write(text = "") ⇒ Object
309 310 311 |
# File 'lib/active_record/migration.rb', line 309 def write(text="") puts(text) if verbose end |