ActiveRecord Migrations Basics

Direct Answer

An Active Record migration is a timestamped Ruby class that describes a database schema change, such as creating a table, adding a column, index, constraint, or foreign key. bin/rails db:migrate applies pending versions and records them; reversible operations in change can be rolled back, while complex changes use explicit up and down. Once a migration has run in shared environments, create a new corrective migration instead of editing history. The schema dump records current structure, while migrations record how it evolved.

Deep Dive & Architecture

Rails compares timestamp versions in the migration directory with versions stored in the database's schema migration metadata. Pending files run in order. This mechanism coordinates schema state; it does not compare the Ruby source of a migration that was already marked complete.

Reversibility is operation-specific. Rails can invert common changes such as creating a table or adding a column when enough information is present. Removing data, executing arbitrary SQL, or transforming values may not have a truthful automatic inverse, so the author must supply one or mark the operation irreversible.

The schema dump represents the current shape used for inspection and loading a fresh database. It is not a replacement for migration review and should not be manually used as a hidden migration. Both the migration and resulting dump normally belong in version control.

Large production changes need staged compatibility. A new nullable column may be deployed before application code writes it, data can be backfilled in controlled batches, then constraints can be tightened later. This allows old and new application processes to operate during a rolling deploy without long locks or invalid reads.

Code Example

class CreateInvoices < ActiveRecord::Migration[8.1]
  def change
    create_table :invoices do |t|
      t.string :number, null: false
      t.references :account, null: false, foreign_key: true
      t.integer :total_cents, null: false
      t.timestamps
    end

    add_index :invoices, :number, unique: true
  end
end

Common Mistakes & Pitfalls

Editing a migration that's already been run (others have it; use a new migration instead), or forgetting db:rollback reversibility.