Class: ActiveRecord::Migration

Inherits:
Object
  • Object
show all
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 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.

Available transformations

  • 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, index_type, index_name): Add a new index with the name of the column, or index_name (if specified) on the column(s). Specify an optional index_type (e.g. UNIQUE).

  • remove_index(table_name, index_name): Remove the index specified by index_name.

Irreversible transformations

Some transformations are destructive in a manner that cannot be reversed. Migrations of that kind should raise an 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, 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.

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

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.

Direct Known Subclasses

Schema

Constant Summary collapse

@@verbose = 
true

Class Method Summary collapse

Class Method Details

.announce(message) ⇒ Object 



246
247
248
249
250
 
# File 'lib/active_record/migration.rb', line 246

def announce(message)
  text = "#{name}: #{message}"
  length = [0, 75 - text.length].max
  write "== %s %s" % [text, "=" * length]
end

.down_using_benchmarks ⇒ Object

:nodoc:



198
199
200
 
# File 'lib/active_record/migration.rb', line 198

def down_using_benchmarks #:nodoc:
  migrate(:down)
end

.method_missing(method, *arguments, &block) ⇒ Object 



272
273
274
275
276
277
 
# File 'lib/active_record/migration.rb', line 272

def method_missing(method, *arguments, &block)
  say_with_time "#{method}(#{arguments.map { |a| a.inspect }.join(", ")})" do
    arguments[0] = Migrator.proper_table_name(arguments.first) unless arguments.empty? || method == :execute
    ActiveRecord::Base.connection.send(method, *arguments, &block)
  end
end

.migrate(direction) ⇒ Object

Execute this migration in the named direction



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/active_record/migration.rb', line 203

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("real_#{direction}") }

  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 



252
253
254
 
# File 'lib/active_record/migration.rb', line 252

def say(message, subitem=false)
  write "#{subitem ? "   ->" : "--"} #{message}"
end

.say_with_time(message) ⇒ Object 



256
257
258
259
260
261
262
 
# File 'lib/active_record/migration.rb', line 256

def say_with_time(message)
  say(message)
  result = nil
  time = Benchmark.measure { result = yield }
  say "%.4fs" % time.real, :subitem
  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.



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/active_record/migration.rb', line 225

def singleton_method_added(sym) #:nodoc:
  return if @ignore_new_methods
  
  begin
    @ignore_new_methods = true

    case sym
      when :up, :down
        klass = (class << self; self; end)
        klass.send(:alias_method, "real_#{sym}", sym)
        klass.send(:alias_method, sym, "#{sym}_using_benchmarks")
    end
  ensure
    @ignore_new_methods = false
  end
end

.suppress_messages ⇒ Object 



264
265
266
267
268
269
270
 
# File 'lib/active_record/migration.rb', line 264

def suppress_messages
  save = verbose
  self.verbose = false
  yield
ensure
  self.verbose = save
end

.up_using_benchmarks ⇒ Object

:nodoc:



194
195
196
 
# File 'lib/active_record/migration.rb', line 194

def up_using_benchmarks #:nodoc:
  migrate(:up)
end

.write(text = "") ⇒ Object 



242
243
244
 
# File 'lib/active_record/migration.rb', line 242

def write(text="")
  puts(text) if verbose
end