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 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 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
. -
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, :datetime, :timestamp, :time, :date, :binary, :boolean. A default value can be specified by passing anoptions
hash like { :default => 11 }. -
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_name)
: Add a new index with the name of the column on the column. -
remove_index(table_name, column_name)
: Remove the index called the same as the column.
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 support for migrations with the script/generate migration my_new_migration
command and with the rake migrate
command that’ll run all the pending migrations. It’ll even create the needed schema_info table automatically if it’s missing.
Database support
Migrations are currently only supported in MySQL and PostgreSQL.
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
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
Class Method Summary collapse
Class Method Details
.down ⇒ Object
114 |
# File 'lib/active_record/migration.rb', line 114 def down() end |
.up ⇒ Object
113 |
# File 'lib/active_record/migration.rb', line 113 def up() end |