Class | ActiveRecord::Migration |
In: |
vendor/rails/activerecord/lib/active_record/migration.rb
|
Parent: | Object |
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 again, 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.column :name, :string t.column :label, :string t.column :value, :text t.column :type, :string t.column :position, :integer 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.
Some transformations are destructive in a manner that cannot be reversed. Migrations of that kind should raise an IrreversibleMigration exception in their down method.
The Rails package has several tools to help create and apply migrations.
To generate a new migration, use script/generate migration MyNewMigration where MyNewMigration is the name of your migration. The generator will create a 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 n MyNewMigration.
To run migrations against the currently configured database, use rake migrate. This will update the database by running all of the pending migrations, creating the schema_info table if missing.
To roll the database back to a previous migration version, use rake migrate VERSION=X where X is the version to which you wish to downgrade. If any of the migrations throw an 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 IrreversibleMigration 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.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.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.
# File vendor/rails/activerecord/lib/active_record/migration.rb, line 245 245: def announce(message) 246: text = "#{name}: #{message}" 247: length = [0, 75 - text.length].max 248: write "== %s %s" % [text, "=" * length] 249: end
# File vendor/rails/activerecord/lib/active_record/migration.rb, line 271 271: def method_missing(method, *arguments, &block) 272: say_with_time "#{method}(#{arguments.map { |a| a.inspect }.join(", ")})" do 273: arguments[0] = Migrator.proper_table_name(arguments.first) unless arguments.empty? || method == :execute 274: ActiveRecord::Base.connection.send(method, *arguments, &block) 275: end 276: end
Execute this migration in the named direction
# File vendor/rails/activerecord/lib/active_record/migration.rb, line 202 202: def migrate(direction) 203: return unless respond_to?(direction) 204: 205: case direction 206: when :up then announce "migrating" 207: when :down then announce "reverting" 208: end 209: 210: result = nil 211: time = Benchmark.measure { result = send("real_#{direction}") } 212: 213: case direction 214: when :up then announce "migrated (%.4fs)" % time.real; write 215: when :down then announce "reverted (%.4fs)" % time.real; write 216: end 217: 218: result 219: end
# File vendor/rails/activerecord/lib/active_record/migration.rb, line 251 251: def say(message, subitem=false) 252: write "#{subitem ? " ->" : "--"} #{message}" 253: end
# File vendor/rails/activerecord/lib/active_record/migration.rb, line 255 255: def say_with_time(message) 256: say(message) 257: result = nil 258: time = Benchmark.measure { result = yield } 259: say "%.4fs" % time.real, :subitem 260: result 261: end
# File vendor/rails/activerecord/lib/active_record/migration.rb, line 263 263: def suppress_messages 264: save = verbose 265: self.verbose = false 266: yield 267: ensure 268: self.verbose = save 269: end