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:

classAddSsl<ActiveRecord::Migration[8.1]defupadd_column:accounts,:ssl_enabled,:boolean,default:trueenddefdownremove_column:accounts,:ssl_enabledendend

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 methodsup anddown that describes the transformations required to implement or remove the migration. These methods can consist of both the migration specific methods likeadd_column andremove_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:

classAddSystemSettings<ActiveRecord::Migration[8.1]defupcreate_table:system_settingsdo|t|t.string:namet.string:labelt.text:valuet.string:typet.integer:positionendSystemSetting.createname:'notice',label:'Use notice?',value:1enddefdowndrop_table:system_settingsendend

This migration first adds thesystem_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 advancedcreate_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. SeeActiveRecord::ConnectionAdapters::SchemaStatements#create_join_table for details.
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.
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 }) – seeActiveRecord::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. SeeActiveRecord::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. SeeActiveRecord::ConnectionAdapters::SchemaStatements#change_column_null for details.
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_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 anActiveRecord::IrreversibleMigration exception in theirdown 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 filetimestamp_my_new_migration.rb in thedb/migrate/ directory wheretimestamp 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 filetimestamp_add_fieldname_to_tablename.rb, which will look like this:

classAddFieldnameToTablename<ActiveRecord::Migration[8.1]defchangeadd_column:tablenames,:fieldname,:stringendend

To run migrations against the currently configured database, usebin/rails db:migrate. This will update the database by running all of the pending migrations, creating theschema_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, usebin/rails db:rollback VERSION=X whereX 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 anActiveRecord::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:

classRemoveEmptyTags<ActiveRecord::Migration[8.1]defupTag.all.each {|tag|tag.destroyiftag.pages.empty? }enddefdown# not much we can do to restore deleted dataraiseActiveRecord::IrreversibleMigration,"Can't recover the deleted tags"endend

Others remove columns when they migrate up instead of down:

classRemoveUnnecessaryItemAttributes<ActiveRecord::Migration[8.1]defupremove_column:items,:incomplete_items_countremove_column:items,:completed_items_countenddefdownadd_column:items,:incomplete_items_countadd_column:items,:completed_items_countendend

And sometimes you need to do something in SQL not abstracted directly by migrations:

classMakeJoinUnique<ActiveRecord::Migration[8.1]defupexecute"ALTER TABLE `pages_linked_pages` ADD UNIQUE `page_id_linked_page_id` (`page_id`,`linked_page_id`)"enddefdownexecute"ALTER TABLE `pages_linked_pages` DROP INDEX `page_id_linked_page_id`"endend

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 toBase#reset_column_information in order to ensure that the model has the latest column data from after the new column was added. Example:

classAddPeopleSalary<ActiveRecord::Migration[8.1]defupadd_column:people,:salary,:integerPerson.reset_column_informationPerson.all.eachdo|p|p.update_attribute:salary,SalaryCalculator.compute(p)endendend

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 settingActiveRecord::Migration.verbose = false.

You can also insert your own messages and benchmarks by using thesay_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.validate_migration_timestamps =true

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

Reversible migrations are migrations that know how to godown for you. You simply supply theup logic, and theMigration system figures out how to execute the down commands for you.

To define a reversible migration, define thechange method in your migration like this:

classTenderloveMigration<ActiveRecord::Migration[8.1]defchangecreate_table(:horses)do|t|t.column:content,:textt.column:remind_at,:datetimeendendend

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 theup anddown methods as before.

If a command cannot be reversed, anActiveRecord::IrreversibleMigration exception will be raised when the migration is moving down.

For a list of commands that are reversible, please seeActiveRecord::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.

classChangeEnum<ActiveRecord::Migration[8.1]disable_ddl_transaction!defupexecute"ALTER TYPE model_size ADD VALUE 'new_value'"endend

Remember that you can still open your own transactions, even if you are in aMigration withself.disable_ddl_transaction!.

Namespace

Methods

#

[]

A

announce

C

D

E

L

load_schema_if_pending!

M

N

P

proper_table_name

R

S

U

up,
up_only

V

verbose

W

write

Attributes

[RW]	name
[RW]	version

Movatterモバイル変換

Class ActiveRecord::Migration<Object

Active Record Migrations¶↑

Available transformations¶↑

Creation¶↑

Modification¶↑

Deletion¶↑

Irreversible transformations¶↑

Running migrations from within Rails¶↑

More examples¶↑

Using a model after changing its table¶↑

Controlling verbosity¶↑

Timestamped Migrations¶↑

Reversible Migrations¶↑

Transactional Migrations¶↑

Attributes

Class Public methods

[](version)Link

check_all_pending!()Link

current_version()Link

disable_ddl_transaction!()Link

load_schema_if_pending!()Link

migrate(direction)Link

new(name = self.class.name, version = nil)Link

verboseLink

Instance Public methods

announce(message)Link

connection()Link

connection_pool()Link

copy(destination, sources, options = {})Link

down()Link

exec_migration(conn, direction)Link

execution_strategy()Link

method_missing(method, *arguments, &block)Link

migrate(direction)Link

next_migration_number(number)Link

proper_table_name(name, options = {})Link

reversible()Link

revert(*migration_classes, &block)Link

reverting?()Link

run(*migration_classes)Link

say(message, subitem = false)Link

say_with_time(message)Link

suppress_messages()Link

up()Link

up_only(&block)Link

write(text = "")Link