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[5.0] 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[5.0] 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.
create_join_table(table_1, table_2, options)
: Creates a join table having its name as the lexical order of the first two arguments. See ActiveRecord::ConnectionAdapters::SchemaStatements#create_join_table for details.
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.
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.
add_foreign_key(from_table, to_table, options)
: Adds a new foreign key. from_table
is the table with the key column, to_table
contains the referenced primary key.
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 } }
).
add_reference(:table_name, :reference_name)
: Adds a new column reference_name_id
by default an integer. See ActiveRecord::ConnectionAdapters::SchemaStatements#add_reference for details.
add_timestamps(table_name, options)
: Adds timestamps (created_at
and updated_at
) columns to table_name
.
change_column(table_name, column_name, type, options)
: Changes the column to a different type using the same parameters as add_column.
change_column_default(table_name, column_name,
default_or_changes)
: Sets a default value for column_name
defined by default_or_changes
on table_name
. Passing a hash containing :from
and :to
as default_or_changes
will make this change reversible in the migration.
change_column_null(table_name, column_name, null, default =
nil)
: Sets or removes a +NOT NULL+ constraint on column_name
. The null
flag indicates whether the value can be NULL
. See ActiveRecord::ConnectionAdapters::SchemaStatements#change_column_null for details.
change_table(name, options)
: Allows to make column alterations to the table called name
. It makes the table object available to a block that can then add/remove columns, indexes or foreign keys to it.
rename_column(table_name, column_name, new_column_name)
: Renames a column but keeps the type and content.
rename_index(table_name, old_name, new_name)
: Renames an index.
rename_table(old_name, new_name)
: Renames the table called old_name
to new_name
.
drop_table(name)
: Drops the table called name
.
drop_join_table(table_1, table_2, options)
: Drops the join table specified by the given arguments.
remove_column(table_name, column_name, type, options)
: Removes the column named column_name
from the table called table_name
.
remove_columns(table_name, *column_names)
: Removes the given columns from the table definition.
remove_foreign_key(from_table, to_table = nil, **options)
: Removes the given foreign key from the table called table_name
.
remove_index(table_name, column: column_names)
: Removes the index specified by column_names
.
remove_index(table_name, name: index_name)
: Removes the index specified by index_name
.
remove_reference(table_name, ref_name, options)
: Removes the reference(s) on table_name
specified by ref_name
.
remove_timestamps(table_name, options)
: Removes the timestamp columns (created_at
and updated_at
) from the table definition.
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.
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.
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.rb
, which will look like this:
class AddFieldnameToTablename < ActiveRecord::Migration[5.0] def change add_column :tablenames, :fieldname, :string end end
To run migrations against the currently configured database, use rails 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 command, 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 rails
db:rollback VERSION=X
where X
is the version to which you wish to downgrade. Alternatively, you can also use the STEP option if you wish to rollback last few migrations. rails db:rollback
STEP=2
will rollback the latest two migrations.
If any of the migrations throw an ActiveRecord::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, and Oracle (all supported databases except DB2).
Not all migrations change the schema. Some just fix the data:
class RemoveEmptyTags < ActiveRecord::Migration[5.0] 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[5.0] 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[5.0] 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
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[5.0] 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
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.
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.timestamped_migrations = false
In application.rb.
Reversible migrations are migrations that know how to go down
for you. You simply supply the up
logic, and the Migration system figures 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[5.0] 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 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
.
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[5.0] 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!
.
# File activerecord/lib/active_record/migration.rb, line 543 def self.[](version) Compatibility.find(version) end
# File activerecord/lib/active_record/migration.rb, line 586 def check_pending!(connection = Base.connection) raise ActiveRecord::PendingMigrationError if connection.migration_context.needs_migration? end
Raises ActiveRecord::PendingMigrationError
error if any migrations are pending.
# File activerecord/lib/active_record/migration.rb, line 547 def self.current_version ActiveRecord::VERSION::STRING.to_f end
# File activerecord/lib/active_record/migration.rb, line 631 def disable_ddl_transaction! @disable_ddl_transaction = true end
Disable the transaction wrapping this migration. You can still create your own transactions even after calling disable_ddl_transaction!
For more details read the “Transactional Migrations” section above.
# File activerecord/lib/active_record/migration.rb, line 590 def load_schema_if_pending! current_config = Base.connection_config all_configs = ActiveRecord::Base.configurations.configs_for(env_name: Rails.env) needs_update = !all_configs.all? do |db_config| Tasks::DatabaseTasks.schema_up_to_date?(db_config.config, ActiveRecord::Base.schema_format, nil, Rails.env, db_config.spec_name) end if needs_update # Roundtrip to Rake to allow plugins to hook into database initialization. root = defined?(ENGINE_ROOT) ? ENGINE_ROOT : Rails.root FileUtils.cd(root) do Base.clear_all_connections! system("bin/rails db:test:prepare") end end # Establish a new connection, the old database may be gone (db:test:prepare uses purge) Base.establish_connection(current_config) check_pending! end
# File activerecord/lib/active_record/migration.rb, line 623 def migrate(direction) new.migrate direction end
# File activerecord/lib/active_record/migration.rb, line 643 def initialize(name = self.class.name, version = nil) @name = name @version = version @connection = nil end
# File activerecord/lib/active_record/migration.rb, line 841 def announce(message) text = "#{version} #{name}: #{message}" length = [0, 75 - text.length].max write "== %s %s" % [text, "=" * length] end
# File activerecord/lib/active_record/migration.rb, line 872 def connection @connection || ActiveRecord::Base.connection end
# File activerecord/lib/active_record/migration.rb, line 894 def copy(destination, sources, options = {}) copied = [] schema_migration = options[:schema_migration] || ActiveRecord::SchemaMigration FileUtils.mkdir_p(destination) unless File.exist?(destination) destination_migrations = ActiveRecord::MigrationContext.new(destination, schema_migration).migrations last = destination_migrations.last sources.each do |scope, path| source_migrations = ActiveRecord::MigrationContext.new(path, schema_migration).migrations source_migrations.each do |migration| source = File.binread(migration.filename) inserted_comment = "# This migration comes from #{scope} (originally #{migration.version})\n" magic_comments = +"" loop do # 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.sub!(/\A(?:#.*\b(?:en)?coding:\s*\S+|#\s*frozen_string_literal:\s*(?:true|false)).*\n/) do |magic_comment| magic_comments << magic_comment; "" end || break end source = "#{magic_comments}#{inserted_comment}#{source}" if duplicate = destination_migrations.detect { |m| m.name == migration.name } if options[:on_skip] && duplicate.scope != scope.to_s options[: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 options[:on_copy].call(scope, migration, old_path) if options[:on_copy] destination_migrations << migration end end copied end
# File activerecord/lib/active_record/migration.rb, line 794 def down self.class.delegate = self return unless self.class.respond_to?(:down) self.class.down end
# File activerecord/lib/active_record/migration.rb, line 822 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
# File activerecord/lib/active_record/migration.rb, line 876 def method_missing(method, *arguments, &block) arg_list = arguments.map(&: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, table_name_options) if [:rename_table, :add_foreign_key].include?(method) || (method == :remove_foreign_key && !arguments.second.is_a?(Hash)) arguments[1] = proper_table_name(arguments.second, table_name_options) end end end return super unless connection.respond_to?(method) connection.send(method, *arguments, &block) end end
# File activerecord/lib/active_record/migration.rb, line 801 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
Execute this migration in the named direction
# File activerecord/lib/active_record/migration.rb, line 954 def next_migration_number(number) if ActiveRecord::Base.timestamped_migrations [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % number].max else SchemaMigration.normalize_migration_number(number) end end
Determines the version number of the next migration.
# File activerecord/lib/active_record/migration.rb, line 945 def proper_table_name(name, options = {}) if name.respond_to? :table_name name.table_name else "#{options[:table_name_prefix]}#{name}#{options[:table_name_suffix]}" end end
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.
# File activerecord/lib/active_record/migration.rb, line 747 def reversible helper = ReversibleBlockHelper.new(reverting?) execute_block { yield helper } end
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[5.0] 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
# File activerecord/lib/active_record/migration.rb, line 690 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 = command_recorder @connection = recorder suppress_messages do connection.revert { yield } end @connection = recorder.delegate recorder.replay(self) end end end
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[5.0] 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 '20121212123456_tenderlove_migration' class FixupTLMigration < ActiveRecord::Migration[5.0] def change revert TenderloveMigration create_table(:apples) do |t| t.string :variety end end end
This command can be nested.
# File activerecord/lib/active_record/migration.rb, line 707 def reverting? connection.respond_to?(:reverting) && connection.reverting end
# File activerecord/lib/active_record/migration.rb, line 774 def run(*migration_classes) opts = migration_classes.extract_options! 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
Runs the given migration classes. Last argument can specify options:
:direction (default is :up)
:revert (default is false)
# File activerecord/lib/active_record/migration.rb, line 849 def say(message, subitem = false) write "#{subitem ? " ->" : "--"} #{message}" end
Takes a message argument and outputs it as is. A second boolean argument can be passed to specify whether to indent or not.
# File activerecord/lib/active_record/migration.rb, line 855 def say_with_time(message) say(message) result = nil time = Benchmark.measure { result = yield } say "%.4fs" % time.real, :subitem say("#{result} rows", :subitem) if result.is_a?(Integer) result end
Outputs text along with how long it took to run its block. If the block returns an integer it assumes it is the number of rows affected.
# File activerecord/lib/active_record/migration.rb, line 865 def suppress_messages save, self.verbose = verbose, false yield ensure self.verbose = save end
Takes a block as an argument and suppresses any output generated by the block.
# File activerecord/lib/active_record/migration.rb, line 788 def up self.class.delegate = self return unless self.class.respond_to?(:up) self.class.up end
# File activerecord/lib/active_record/migration.rb, line 766 def up_only execute_block { yield } unless reverting? end
Used to specify an operation that is only run when migrating up (for example, populating a new column with its initial values).
In the following example, the new column published
will be given the value true
for all existing records.
class AddPublishedToPosts < ActiveRecord::Migration[5.2] def change add_column :posts, :published, :boolean, default: false up_only do execute "update posts set published = 'true'" end end end
# File activerecord/lib/active_record/migration.rb, line 837 def write(text = "") puts(text) if verbose end
© 2004–2019 David Heinemeier Hansson
Licensed under the MIT License.