Class: ActiveRecord::Migration
- Inherits:
-
Object
- Object
- ActiveRecord::Migration
- Defined in:
- lib/active_record/migration.rb,
lib/active_record/migration/join_table.rb,
lib/active_record/migration/command_recorder.rb
Overview
Active Record Migrations
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 up
add_column :accounts, :ssl_enabled, :boolean, default: true
end
def 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 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 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 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 asadd_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
. -
change_table(name, options)
: Allows to make column alterations to the table calledname
. It makes the table object available to a block that can then add/remove columns, indexes or foreign keys to it. -
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, type, options)
: 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
,:unique
(e.g.{ name: 'users_name_index', unique: true }
) and:order
(e.g.{ order: { name: :desc } }
). -
remove_index(table_name, column: column_name)
: Removes the index specified bycolumn_name
. -
remove_index(table_name, 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
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 up
and 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 up
add_column :tablenames, :fieldname, :string
end
def 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.
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 up
Tag.all.each { |tag| tag.destroy if tag.pages.empty? }
end
def 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 up
remove_column :items, :incomplete_items_count
remove_column :items, :completed_items_count
end
def 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 up
execute "ALTER TABLE `pages_linked_pages` ADD UNIQUE `page_id_linked_page_id` (`page_id`,`linked_page_id`)"
end
def 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 up
add_column :people, :salary, :integer
Person.reset_column_information
Person.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 up
...
say_with_time "Updating salaries..." do
Person.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 application.rb.
Reversible Migrations
Starting with Rails 3.1, you will be able to define reversible migrations. Reversible migrations are migrations that know how to go down
for you. You simply supply the up
logic, and the Migration system will figure out how to execute the down commands for you.
To define a reversible migration, define the change
method in your migration like this:
class TenderloveMigration < ActiveRecord::Migration
def change
create_table(:horses) do |t|
t.column :content, :text
t.column :remind_at, :datetime
end
end
end
This migration will create the horses table for you on the way up, and automatically figure out how to drop the table on the way down.
Some commands like remove_column
cannot be reversed. If you care to define how to move up and down in these cases, you should define the up
and down
methods as before.
If a command cannot be reversed, an ActiveRecord::IrreversibleMigration
exception will be raised when the migration is moving down.
For a list of commands that are reversible, please see ActiveRecord::Migration::CommandRecorder
.
Transactional Migrations
If the database adapter supports DDL transactions, all migrations will automatically be wrapped in a transaction. There are queries that you can’t execute inside a transaction though, and for these situations you can turn the automatic transactions off.
class ChangeEnum < ActiveRecord::Migration
disable_ddl_transaction!
def up
execute "ALTER TYPE model_size ADD VALUE 'new_value'"
end
end
Remember that you can still open your own transactions, even if you are in a Migration with self.disable_ddl_transaction!
.
Direct Known Subclasses
Defined Under Namespace
Modules: JoinTable Classes: CheckPending, CommandRecorder, ReversibleBlockHelper
Class Attribute Summary collapse
-
.delegate ⇒ Object
:nodoc:.
-
.disable_ddl_transaction ⇒ Object
:nodoc:.
Instance Attribute Summary collapse
-
#name ⇒ Object
Returns the value of attribute name.
-
#version ⇒ Object
Returns the value of attribute version.
Class Method Summary collapse
- .check_pending!(connection = Base.connection) ⇒ Object
-
.disable_ddl_transaction! ⇒ Object
Disable DDL transactions for this migration.
- .load_schema_if_pending! ⇒ Object
-
.maintain_test_schema! ⇒ Object
:nodoc:.
-
.method_missing(name, *args, &block) ⇒ Object
:nodoc:.
- .migrate(direction) ⇒ Object
Instance Method Summary collapse
- #announce(message) ⇒ Object
- #connection ⇒ Object
- #copy(destination, sources, options = {}) ⇒ Object
-
#disable_ddl_transaction ⇒ Object
:nodoc:.
- #down ⇒ Object
- #exec_migration(conn, direction) ⇒ Object
-
#initialize(name = self.class.name, version = nil) ⇒ Migration
constructor
A new instance of Migration.
- #method_missing(method, *arguments, &block) ⇒ Object
-
#migrate(direction) ⇒ Object
Execute this migration in the named direction.
-
#next_migration_number(number) ⇒ Object
Determines the version number of the next migration.
-
#proper_table_name(name, options = {}) ⇒ Object
Finds the correct table name given an Active Record object.
-
#reversible ⇒ Object
Used to specify an operation that can be run in one direction or another.
-
#revert(*migration_classes) ⇒ Object
Reverses the migration commands for the given block and the given migrations.
- #reverting? ⇒ Boolean
-
#run(*migration_classes) ⇒ Object
Runs the given migration classes.
- #say(message, subitem = false) ⇒ Object
- #say_with_time(message) ⇒ Object
- #suppress_messages ⇒ Object
- #table_name_options(config = ActiveRecord::Base) ⇒ Object
- #up ⇒ Object
- #write(text = "") ⇒ Object
Constructor Details
#initialize(name = self.class.name, version = nil) ⇒ Migration
Returns a new instance of Migration.
433 434 435 436 437 |
# File 'lib/active_record/migration.rb', line 433 def initialize(name = self.class.name, version = nil) @name = name @version = version @connection = nil end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *arguments, &block) ⇒ Object
645 646 647 648 649 650 651 652 653 654 655 656 657 658 |
# File 'lib/active_record/migration.rb', line 645 def method_missing(method, *arguments, &block) arg_list = arguments.map{ |a| a.inspect } * ', ' say_with_time "#{method}(#{arg_list})" do unless @connection.respond_to? :revert unless arguments.empty? || [:execute, :enable_extension, :disable_extension].include?(method) arguments[0] = proper_table_name(arguments.first, ) arguments[1] = proper_table_name(arguments.second, ) if method == :rename_table end end return super unless connection.respond_to?(method) connection.send(method, *arguments, &block) end end |
Class Attribute Details
.delegate ⇒ Object
:nodoc:
385 386 387 |
# File 'lib/active_record/migration.rb', line 385 def delegate @delegate end |
.disable_ddl_transaction ⇒ Object
:nodoc:
386 387 388 |
# File 'lib/active_record/migration.rb', line 386 def disable_ddl_transaction @disable_ddl_transaction end |
Instance Attribute Details
#name ⇒ Object
Returns the value of attribute name.
431 432 433 |
# File 'lib/active_record/migration.rb', line 431 def name @name end |
#version ⇒ Object
Returns the value of attribute version.
431 432 433 |
# File 'lib/active_record/migration.rb', line 431 def version @version end |
Class Method Details
.check_pending!(connection = Base.connection) ⇒ Object
388 389 390 |
# File 'lib/active_record/migration.rb', line 388 def check_pending!(connection = Base.connection) raise ActiveRecord::PendingMigrationError if ActiveRecord::Migrator.needs_migration?(connection) end |
.disable_ddl_transaction! ⇒ Object
Disable DDL transactions for this migration.
421 422 423 |
# File 'lib/active_record/migration.rb', line 421 def disable_ddl_transaction! @disable_ddl_transaction = true end |
.load_schema_if_pending! ⇒ Object
392 393 394 395 396 397 398 399 400 401 402 403 404 |
# File 'lib/active_record/migration.rb', line 392 def load_schema_if_pending! if ActiveRecord::Migrator.needs_migration? # Roundrip to Rake to allow plugins to hook into database initialization. FileUtils.cd Rails.root do current_config = Base.connection_config Base.clear_all_connections! system("bin/rake db:test:prepare") # Establish a new connection, the old database may be gone (db:test:prepare uses purge) Base.establish_connection(current_config) end check_pending! end end |
.maintain_test_schema! ⇒ Object
:nodoc:
406 407 408 409 410 |
# File 'lib/active_record/migration.rb', line 406 def maintain_test_schema! # :nodoc: if ActiveRecord::Base.maintain_test_schema { load_schema_if_pending! } end end |
.method_missing(name, *args, &block) ⇒ Object
:nodoc:
412 413 414 |
# File 'lib/active_record/migration.rb', line 412 def method_missing(name, *args, &block) # :nodoc: (delegate || superclass.delegate).send(name, *args, &block) end |
.migrate(direction) ⇒ Object
416 417 418 |
# File 'lib/active_record/migration.rb', line 416 def migrate(direction) new.migrate direction end |
Instance Method Details
#announce(message) ⇒ Object
615 616 617 618 619 |
# File 'lib/active_record/migration.rb', line 615 def announce() text = "#{version} #{name}: #{}" length = [0, 75 - text.length].max write "== %s %s" % [text, "=" * length] end |
#connection ⇒ Object
641 642 643 |
# File 'lib/active_record/migration.rb', line 641 def connection @connection || ActiveRecord::Base.connection end |
#copy(destination, sources, options = {}) ⇒ Object
660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 |
# File 'lib/active_record/migration.rb', line 660 def copy(destination, sources, = {}) copied = [] FileUtils.mkdir_p(destination) unless File.exist?(destination) destination_migrations = ActiveRecord::Migrator.migrations(destination) last = destination_migrations.last sources.each do |scope, path| source_migrations = ActiveRecord::Migrator.migrations(path) source_migrations.each do |migration| source = File.binread(migration.filename) inserted_comment = "# This migration comes from #{scope} (originally #{migration.version})\n" if /\A#.*\b(?:en)?coding:\s*\S+/ =~ source # If we have a magic comment in the original migration, # insert our comment after the first newline(end of the magic comment line) # so the magic keep working. # Note that magic comments must be at the first line(except sh-bang). source[/\n/] = "\n#{inserted_comment}" else source = "#{inserted_comment}#{source}" end if duplicate = destination_migrations.detect { |m| m.name == migration.name } if [:on_skip] && duplicate.scope != scope.to_s [:on_skip].call(scope, migration) end next end migration.version = next_migration_number(last ? last.version + 1 : 0).to_i new_path = File.join(destination, "#{migration.version}_#{migration.name.underscore}.#{scope}.rb") old_path, migration.filename = migration.filename, new_path last = migration File.binwrite(migration.filename, source) copied << migration [:on_copy].call(scope, migration, old_path) if [:on_copy] destination_migrations << migration end end copied end |
#disable_ddl_transaction ⇒ Object
:nodoc:
426 427 428 |
# File 'lib/active_record/migration.rb', line 426 def disable_ddl_transaction # :nodoc: self.class.disable_ddl_transaction end |
#down ⇒ Object
568 569 570 571 572 |
# File 'lib/active_record/migration.rb', line 568 def down self.class.delegate = self return unless self.class.respond_to?(:down) self.class.down end |
#exec_migration(conn, direction) ⇒ Object
596 597 598 599 600 601 602 603 604 605 606 607 608 609 |
# File 'lib/active_record/migration.rb', line 596 def exec_migration(conn, direction) @connection = conn if respond_to?(:change) if direction == :down revert { change } else change end else send(direction) end ensure @connection = nil end |
#migrate(direction) ⇒ Object
Execute this migration in the named direction
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 |
# File 'lib/active_record/migration.rb', line 575 def migrate(direction) return unless respond_to?(direction) case direction when :up then announce "migrating" when :down then announce "reverting" end time = nil ActiveRecord::Base.connection_pool.with_connection do |conn| time = Benchmark.measure do exec_migration(conn, direction) end end case direction when :up then announce "migrated (%.4fs)" % time.real; write when :down then announce "reverted (%.4fs)" % time.real; write end end |
#next_migration_number(number) ⇒ Object
Determines the version number of the next migration.
717 718 719 720 721 722 723 |
# File 'lib/active_record/migration.rb', line 717 def next_migration_number(number) if ActiveRecord::Base. [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % number].max else SchemaMigration.normalize_migration_number(number) end end |
#proper_table_name(name, options = {}) ⇒ Object
Finds the correct table name given an Active Record object. Uses the Active Record object’s own table_name, or pre/suffix from the options passed in.
708 709 710 711 712 713 714 |
# File 'lib/active_record/migration.rb', line 708 def proper_table_name(name, = {}) if name.respond_to? :table_name name.table_name else "#{[:table_name_prefix]}#{name}#{[:table_name_suffix]}" end end |
#reversible ⇒ Object
Used to specify an operation that can be run in one direction or another. Call the methods up
and down
of the yielded object to run a block only in one given direction. The whole block will be called in the right order within the migration.
In the following example, the looping on users will always be done when the three columns ‘first_name’, ‘last_name’ and ‘full_name’ exist, even when migrating down:
class SplitNameMigration < ActiveRecord::Migration
def change
add_column :users, :first_name, :string
add_column :users, :last_name, :string
reversible do |dir|
User.reset_column_information
User.all.each do |u|
dir.up { u.first_name, u.last_name = u.full_name.split(' ') }
dir.down { u.full_name = "#{u.first_name} #{u.last_name}" }
u.save
end
end
revert { add_column :users, :full_name, :string }
end
end
539 540 541 542 |
# File 'lib/active_record/migration.rb', line 539 def reversible helper = ReversibleBlockHelper.new(reverting?) execute_block{ yield helper } end |
#revert(*migration_classes) ⇒ Object
Reverses the migration commands for the given block and the given migrations.
The following migration will remove the table ‘horses’ and create the table ‘apples’ on the way up, and the reverse on the way down.
class FixTLMigration < ActiveRecord::Migration
def change
revert do
create_table(:horses) do |t|
t.text :content
t.datetime :remind_at
end
end
create_table(:apples) do |t|
t.string :variety
end
end
end
Or equivalently, if TenderloveMigration
is defined as in the documentation for Migration:
require_relative '2012121212_tenderlove_migration'
class FixupTLMigration < ActiveRecord::Migration
def change
revert TenderloveMigration
create_table(:apples) do |t|
t.string :variety
end
end
end
This command can be nested.
480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 |
# File 'lib/active_record/migration.rb', line 480 def revert(*migration_classes) run(*migration_classes.reverse, revert: true) unless migration_classes.empty? if block_given? if @connection.respond_to? :revert @connection.revert { yield } else recorder = CommandRecorder.new(@connection) @connection = recorder do @connection.revert { yield } end @connection = recorder.delegate recorder.commands.each do |cmd, args, block| send(cmd, *args, &block) end end end end |
#reverting? ⇒ Boolean
499 500 501 |
# File 'lib/active_record/migration.rb', line 499 def reverting? @connection.respond_to?(:reverting) && @connection.reverting end |
#run(*migration_classes) ⇒ Object
Runs the given migration classes. Last argument can specify options:
-
:direction (default is :up)
-
:revert (default is false)
548 549 550 551 552 553 554 555 556 557 558 559 560 |
# File 'lib/active_record/migration.rb', line 548 def run(*migration_classes) opts = migration_classes. dir = opts[:direction] || :up dir = (dir == :down ? :up : :down) if opts[:revert] if reverting? # If in revert and going :up, say, we want to execute :down without reverting, so revert { run(*migration_classes, direction: dir, revert: true) } else migration_classes.each do |migration_class| migration_class.new.exec_migration(@connection, dir) end end end |
#say(message, subitem = false) ⇒ Object
621 622 623 |
# File 'lib/active_record/migration.rb', line 621 def say(, subitem=false) write "#{subitem ? " ->" : "--"} #{}" end |
#say_with_time(message) ⇒ Object
625 626 627 628 629 630 631 632 |
# File 'lib/active_record/migration.rb', line 625 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 |
#suppress_messages ⇒ Object
634 635 636 637 638 639 |
# File 'lib/active_record/migration.rb', line 634 def save, self.verbose = verbose, false yield ensure self.verbose = save end |
#table_name_options(config = ActiveRecord::Base) ⇒ Object
725 726 727 728 729 730 |
# File 'lib/active_record/migration.rb', line 725 def (config = ActiveRecord::Base) { table_name_prefix: config.table_name_prefix, table_name_suffix: config.table_name_suffix } end |
#up ⇒ Object
562 563 564 565 566 |
# File 'lib/active_record/migration.rb', line 562 def up self.class.delegate = self return unless self.class.respond_to?(:up) self.class.up end |
#write(text = "") ⇒ Object
611 612 613 |
# File 'lib/active_record/migration.rb', line 611 def write(text="") puts(text) if verbose end |