ri > ActiveRecord::Migration

= ActiveRecord::Migration < Object

(from /home/chedong/.local/share/rdoc)
------------------------------------------------------------------------
= 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[6.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[6.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 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.

=== 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 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.

=== Deletion

* 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.

== 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
  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[6.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 ActiveRecord::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[6.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[6.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[6.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[6.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).

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 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[6.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.

== 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[6.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!.



------------------------------------------------------------------------
= Class methods:

  []
  check_pending!
  current_version
  disable_ddl_transaction!
  load_schema_if_pending!
  migrate
  new

= Instance methods:

  announce
  connection
  copy
  down
  exec_migration
  method_missing
  migrate
  name
  next_migration_number
  proper_table_name
  reversible
  revert
  reverting?
  run
  say
  say_with_time
  suppress_messages
  up
  up_only
  version
  write

= Attributes:

  attr_accessor name
  attr_accessor version