Class: ActiveRecord::Migration
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Inherits: | Object |
Defined in: | activerecord/lib/active_record/migration.rb, activerecord/lib/active_record/migration/command_recorder.rb, activerecord/lib/active_record/migration/compatibility.rb, activerecord/lib/active_record/migration/default_strategy.rb, activerecord/lib/active_record/migration/execution_strategy.rb, activerecord/lib/active_record/migration/join_table.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[8.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[8.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.
Available transformations
Creation
-
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 asadd_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 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. -
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 columnreference_name_id
by default an integer. See ActiveRecord::ConnectionAdapters::SchemaStatements#add_reference for details. -
add_timestamps(table_name, options)
: Adds timestamps (created_at
andupdated_at
) columns totable_name
.
Modification
-
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 forcolumn_name
defined bydefault_or_changes
ontable_name
. Passing a hash containing:from
and:to
asdefault_or_changes
will make this change reversible in the migration. -
change_column_null(table_name, column_name, null, default = nil)
: Sets or removes aNOT NULL
constraint oncolumn_name
. Thenull
flag indicates whether the value can beNULL
. 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 calledold_name
tonew_name
.
Deletion
-
drop_table(*names)
: Drops the given tables. -
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 namedcolumn_name
from the table calledtable_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 calledtable_name
. -
remove_index(table_name, column: column_names)
: Removes the index specified bycolumn_names
. -
remove_index(table_name, name: index_name)
: Removes the index specified byindex_name
. -
remove_reference(table_name, ref_name, options)
: Removes the reference(s) ontable_name
specified byref_name
. -
remove_timestamps(table_name, options)
: Removes the timestamp columns (created_at
andupdated_at
) from the table definition.
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, you can use
$ bin/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.
$ bin/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[8.0]
def change
add_column :tablenames, :fieldname, :string
end
end
To run migrations against the currently configured database, use bin/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 bin/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. bin/rails db:rollback STEP=2
will rollback the latest two migrations.
If any of the migrations throw an IrreversibleMigration
exception, that step will fail and you’ll have some manual work to do.
More examples
Not all migrations change the schema. Some just fix the data:
class RemoveEmptyTags < ActiveRecord::Migration[8.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[8.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[8.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
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[8.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
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.
Timestamped Migrations
By default, Rails generates migrations that look like:
20080717013526_your_migration_name.rb
The prefix is a generation timestamp (in UTC). Timestamps should not be modified manually. To validate that migration timestamps adhere to the format Active Record expects, you can use the following configuration option:
config.active_record. = true
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
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[8.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 IrreversibleMigration
exception will be raised when the migration is moving down.
For a list of commands that are reversible, please see 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[8.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!
.
Constant Summary
-
MigrationFilenameRegexp =
Internal use only
# File 'activerecord/lib/active_record/migration.rb', line 637/\A([0-9]+)_([_a-z0-9]*)\.?([_a-z0-9]*)?\.rb\z/
Class Attribute Summary
-
.verbose
(also: #verbose)
rw
Specifies if migrations will write the actions they are taking to the console as they happen, along with benchmarks describing how long each step took.
- .any_schema_needs_update? ⇒ Boolean readonly private
- .delegate rw Internal use only
- .disable_ddl_transaction rw Internal use only
Class Method Summary
- .[](version)
-
.check_all_pending!
Raises
PendingMigrationError
error if any migrations are pending for all database configurations in an environment. - .current_version
-
.disable_ddl_transaction!
Disable the transaction wrapping this migration.
- .load_schema_if_pending!
- .migrate(direction)
- .new(name = self.class.name, version = nil) ⇒ Migration constructor
- .db_configs_in_current_env private
- .env private
- .load_schema! private
- .pending_migrations private
- .check_pending_migrations Internal use only
- .inherited(subclass) Internal use only
- .maintain_test_schema! Internal use only
- .method_missing(name) Internal use only
- .nearest_delegate Internal use only
- .valid_version_format?(version_string) ⇒ Boolean Internal use only
Instance Attribute Summary
- #name rw
- #reverting? ⇒ Boolean readonly
-
#verbose
rw
Alias for class attribute .verbose
- #version rw
Instance Method Summary
- #announce(message)
- #connection
- #connection_pool
- #copy(destination, sources, options = {})
- #down
- #exec_migration(conn, direction)
- #execution_strategy
- #method_missing(method, *arguments, &block)
-
#migrate(direction)
Execute this migration in the named direction.
-
#next_migration_number(number)
Determines the version number of the next migration.
-
#proper_table_name(name, options = {})
Finds the correct table name given an Active Record object.
-
#reversible
Used to specify an operation that can be run in one direction or another.
-
#revert(*migration_classes, &block)
Reverses the migration commands for the given block and the given migrations.
-
#run(*migration_classes)
Runs the given migration classes.
-
#say(message, subitem = false)
Takes a message argument and outputs it as is.
-
#say_with_time(message)
Outputs text along with how long it took to run its block.
-
#suppress_messages
Takes a block as an argument and suppresses any output generated by the block.
- #up
-
#up_only(&block)
Used to specify an operation that is only run when migrating up (for example, populating a new column with its initial values).
- #write(text = "")
- #command_recorder private
- #execute_block private
- #format_arguments(arguments) private
- #internal_option?(option_name) ⇒ Boolean private
- #disable_ddl_transaction Internal use only
-
#table_name_options(config = ActiveRecord::Base)
Internal use only
Builds a hash for use in #proper_table_name using the Active Record object’s table_name prefix and suffix.
Constructor Details
.new(name = self.class.name, version = nil) ⇒ Migration
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *arguments, &block)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1044
def method_missing(method, *arguments, &block) say_with_time "#{method}(#{format_arguments(arguments)})" do unless connection.respond_to? :revert unless arguments.empty? || [:execute, :enable_extension, :disable_extension].include?(method) arguments[0] = proper_table_name(arguments.first, ) if method == :rename_table || (method == :remove_foreign_key && !arguments.second.is_a?(Hash)) arguments[1] = proper_table_name(arguments.second, ) end end end return super unless execution_strategy.respond_to?(method) execution_strategy.send(method, *arguments, &block) end end
Class Attribute Details
.any_schema_needs_update? ⇒ Boolean
(readonly, private)
[ GitHub ]
# File 'activerecord/lib/active_record/migration.rb', line 748
def any_schema_needs_update? !db_configs_in_current_env.all? do |db_config| Tasks::DatabaseTasks.schema_up_to_date?(db_config, ActiveRecord.schema_format) end end
.delegate (rw)
# File 'activerecord/lib/active_record/migration.rb', line 684
attr_accessor :delegate # :nodoc:
.disable_ddl_transaction (rw)
# File 'activerecord/lib/active_record/migration.rb', line 685
attr_accessor :disable_ddl_transaction # :nodoc:
.verbose (rw) Also known as: #verbose
Specifies if migrations will write the actions they are taking to the console as they happen, along with benchmarks describing how long each step took. Defaults to true.
# File 'activerecord/lib/active_record/migration.rb', line 797
cattr_accessor :verbose
Class Method Details
.[](version)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 629
def self.[](version) Compatibility.find(version) end
.check_all_pending!
Raises PendingMigrationError
error if any migrations are pending for all database configurations in an environment.
# File 'activerecord/lib/active_record/migration.rb', line 693
def check_all_pending! pending_migrations = [] ActiveRecord::Tasks::DatabaseTasks.with_temporary_pool_for_each(env: env) do |pool| if pending = pool.migration_context.open.pending_migrations pending_migrations << pending end end migrations = pending_migrations.flatten if migrations.any? raise ActiveRecord::PendingMigrationError.new(pending_migrations: migrations) end end
.check_pending_migrations
# File 'activerecord/lib/active_record/migration.rb', line 739
def check_pending_migrations # :nodoc: migrations = pending_migrations if migrations.any? raise ActiveRecord::PendingMigrationError.new(pending_migrations: migrations) end end
.current_version
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 633
def self.current_version ActiveRecord::VERSION::STRING.to_f end
.db_configs_in_current_env (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 754
def db_configs_in_current_env ActiveRecord::Base.configurations.configs_for(env_name: env) end
.disable_ddl_transaction!
Disable the transaction wrapping this migration. You can still create your own transactions even after calling #disable_ddl_transaction!
For more details read the Migration
.
# File 'activerecord/lib/active_record/migration.rb', line 735
def disable_ddl_transaction! @disable_ddl_transaction = true end
.env (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 772
def env ActiveRecord::ConnectionHandling::DEFAULT_ENV.call end
.inherited(subclass)
# File 'activerecord/lib/active_record/migration.rb', line 617
def self.inherited(subclass) # :nodoc: super if subclass.superclass == Migration major = ActiveRecord::VERSION::MAJOR minor = ActiveRecord::VERSION::MINOR raise StandardError, "Directly inheriting from ActiveRecord::Migration is not supported. " \ "Please specify the Active Record release the migration was written for:\n" \ "\n" \ " class #{subclass} < ActiveRecord::Migration[#{major}.#{minor}]" end end
.load_schema! (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 776
def load_schema! # Roundtrip to Rake to allow plugins to hook into database initialization. root = defined?(ENGINE_ROOT) ? ENGINE_ROOT : Rails.root FileUtils.cd(root) do Base.connection_handler.clear_all_connections!(:all) system("bin/rails db:test:prepare") end end
.load_schema_if_pending!
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 709
def load_schema_if_pending! if any_schema_needs_update? load_schema! end check_pending_migrations end
.maintain_test_schema!
# File 'activerecord/lib/active_record/migration.rb', line 717
def maintain_test_schema! # :nodoc: if ActiveRecord.maintain_test_schema { load_schema_if_pending! } end end
.method_missing(name)
# File 'activerecord/lib/active_record/migration.rb', line 723
def method_missing(name, ...) # :nodoc: nearest_delegate.send(name, ...) end
.migrate(direction)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 727
def migrate(direction) new.migrate direction end
.nearest_delegate
# File 'activerecord/lib/active_record/migration.rb', line 687
def nearest_delegate # :nodoc: delegate || superclass.nearest_delegate end
.pending_migrations (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 758
def pending_migrations pending_migrations = [] ActiveRecord::Base.configurations.configs_for(env_name: env).each do |db_config| ActiveRecord::PendingMigrationConnection.with_temporary_pool(db_config) do |pool| if pending = pool.migration_context.open.pending_migrations pending_migrations << pending end end end pending_migrations.flatten end
.valid_version_format?(version_string) ⇒ Boolean
# File 'activerecord/lib/active_record/migration.rb', line 639
def self.valid_version_format?(version_string) # :nodoc: [ MigrationFilenameRegexp, /\A\d(_?\d)*\z/ # integer with optional underscores ].any? { |pattern| pattern.match?(version_string) } end
Instance Attribute Details
#name (rw)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 798
attr_accessor :name, :version
#reverting? ⇒ Boolean
(readonly)
[ GitHub ]
# File 'activerecord/lib/active_record/migration.rb', line 869
def reverting? connection.respond_to?(:reverting) && connection.reverting end
#verbose (rw)
Alias for class attribute .verbose
# File 'activerecord/lib/active_record/migration.rb', line 797
cattr_accessor :verbose
#version (rw)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 798
attr_accessor :name, :version
Instance Method Details
#announce(message)
[ GitHub ]#command_recorder (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1170
def command_recorder CommandRecorder.new(connection) end
#connection
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1036
def connection @connection || ActiveRecord::Tasks::DatabaseTasks.migration_connection end
#connection_pool
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1040
def connection_pool @pool || ActiveRecord::Tasks::DatabaseTasks.migration_connection_pool end
#copy(destination, sources, options = {})
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1061
def copy(destination, sources, = {}) copied = [] FileUtils.mkdir_p(destination) unless File.exist?(destination) schema_migration = SchemaMigration::NullSchemaMigration.new = InternalMetadata::NullInternalMetadata.new 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 if !magic_comments.empty? && source.start_with?("\n") magic_comments << "\n" source = source[1..-1] end source = "#{magic_comments}#{inserted_comment}#{source}" 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
# File 'activerecord/lib/active_record/migration.rb', line 787
def disable_ddl_transaction # :nodoc: self.class.disable_ddl_transaction end
#down
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 957
def down self.class.delegate = self return unless self.class.respond_to?(:down) self.class.down end
#exec_migration(conn, direction)
[ GitHub ]#execute_block (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1146
def execute_block if connection.respond_to? :execute_block super # use normal delegation to record the block else yield end end
#execution_strategy
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 807
def execution_strategy @execution_strategy ||= ActiveRecord.migration_strategy.new(self) end
#format_arguments(arguments) (private)
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1154
def format_arguments(arguments) arg_list = arguments[0...-1].map(&:inspect) last_arg = arguments.last if last_arg.is_a?(Hash) last_arg = last_arg.reject { |k, _v| internal_option?(k) } arg_list << last_arg.inspect unless last_arg.empty? else arg_list << last_arg.inspect end arg_list.join(", ") end
#internal_option?(option_name) ⇒ Boolean
(private)
# File 'activerecord/lib/active_record/migration.rb', line 1166
def internal_option?(option_name) option_name.start_with?("_") end
#migrate(direction)
Execute this migration in the named direction
# File 'activerecord/lib/active_record/migration.rb', line 964
def migrate(direction) return unless respond_to?(direction) case direction when :up then announce "migrating" when :down then announce "reverting" end time_elapsed = nil ActiveRecord::Tasks::DatabaseTasks.migration_connection.pool.with_connection do |conn| time_elapsed = ActiveSupport::Benchmark.realtime do exec_migration(conn, direction) end end case direction when :up then announce "migrated (%.4fs)" % time_elapsed; write when :down then announce "reverted (%.4fs)" % time_elapsed; write end end
#next_migration_number(number)
Determines the version number of the next migration.
# File 'activerecord/lib/active_record/migration.rb', line 1128
def next_migration_number(number) if ActiveRecord. [Time.now.utc.strftime("%Y%m%d%H%M%S"), "%.14d" % number].max else "%.3d" % number.to_i end end
#proper_table_name(name, options = {})
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.
#reversible
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[8.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 909
def reversible helper = ReversibleBlockHelper.new(reverting?) execute_block { yield helper } end
#revert(*migration_classes, &block)
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[8.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[8.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 852
def revert(*migration_classes, &block) run(*migration_classes.reverse, revert: true) unless migration_classes.empty? if block_given? if connection.respond_to? :revert connection.revert(&block) else recorder = command_recorder @connection = recorder do connection.revert(&block) end @connection = recorder.delegate recorder.replay(self) end end end
#run(*migration_classes)
Runs the given migration classes. Last argument can specify options:
-
:direction
- Default is:up
. -
:revert
- Default isfalse
.
# File 'activerecord/lib/active_record/migration.rb', line 937
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)
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 1013
def say(, subitem = false) write "#{subitem ? " ->" : "--"} #{}" end
#say_with_time(message)
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.
#suppress_messages
Takes a block as an argument and suppresses any output generated by the block.
#table_name_options(config = ActiveRecord::Base)
Builds a hash for use in #proper_table_name using the Active Record object’s table_name prefix and suffix
# File 'activerecord/lib/active_record/migration.rb', line 1138
def (config = ActiveRecord::Base) # :nodoc: { table_name_prefix: config.table_name_prefix, table_name_suffix: config.table_name_suffix } end
#up
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 951
def up self.class.delegate = self return unless self.class.respond_to?(:up) self.class.up end
#up_only(&block)
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[8.0]
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 928
def up_only(&block) execute_block(&block) unless reverting? end
#write(text = "")
[ GitHub ]# File 'activerecord/lib/active_record/migration.rb', line 1001
def write(text = "") puts(text) if verbose end