Rails Migrations Expert Skill

Rails Migrations Expert

Write safe, reversible, forward-only migrations for Rails 8.1 applications.

Golden Rules

These are non-negotiable. Violating any of them causes real production pain.

1. NEVER Edit Old Migrations

Once a migration has been committed (especially if run in production), it is frozen forever. Don't touch it. Write a new migration instead.

# BAD — editing an existing, committed migration
class CreateUsers < ActiveRecord::Migration[8.1]
  def change
    create_table :users do |t|
      t.string :email
      t.string :name  # ← sneaking this in after the fact
    end
  end
end

# GOOD — new migration to add the column
class AddNameToUsers < ActiveRecord::Migration[8.1]
  def change
    add_column :users, :name, :string
  end
end

Why: Other developers and environments have already run the old version. Editing it breaks db:migrate for everyone and causes schema drift.

Exception: A migration you just generated that hasn't been committed or run anywhere else — edit freely.

2. NEVER Modify the Database Directly

All schema changes go through migrations. No exceptions.

# BAD
sqlite3 db/development.sqlite3 "ALTER TABLE users ADD COLUMN name TEXT"

# GOOD
bin/rails generate migration AddNameToUsers name:string
bin/rails db:migrate

Why: Direct changes aren't tracked, schema.rb falls out of sync, and other environments won't have the changes.

3. Always Move Forward

Migrations are append-only. To fix mistakes, write a new migration.

# Wrong column type? New migration.
class ChangePostsBodyToText < ActiveRecord::Migration[8.1]
  def up
    change_column :posts, :body, :text
  end

  def down
    change_column :posts, :body, :string
  end
end

# Need to remove a column? New migration.
class RemoveObsoleteColumnFromUsers < ActiveRecord::Migration[8.1]
  def change
    remove_column :users, :obsolete_field, :string
  end
end

Instructions

Step 1: Understand What You're Changing

Before writing a migration, check the current schema:

# Check current schema
cat db/schema.rb | grep -A 20 "create_table \"users\""

# Check migration status
bin/rails db:migrate:status

# Check existing migrations
ls -la db/migrate/

Know the current state before changing it.

Step 2: Generate the Migration

Use Rails generators — they create the file with the right timestamp and class structure. Name your migrations descriptively using Rails conventions:

# Creating a table (CreateXxx)
bin/rails generate migration CreatePosts title:string body:text published_at:datetime

# Adding columns (AddXxxToYyy)
bin/rails generate migration AddCategoryToPosts category:string

# Removing columns (RemoveXxxFromYyy)
bin/rails generate migration RemoveLegacyFieldFromUsers legacy_field:string

# Adding a reference/foreign key
bin/rails generate migration AddUserRefToPosts user:references

# Adding an index
bin/rails generate migration AddPartNumberToProducts part_number:string:index

# General changes (descriptive name)
bin/rails generate migration ChangePostsBodyToText

Generator shortcuts:

name:string — default type is string if omitted, so name alone works
user:references — creates user_id column + index + foreign key
price:decimal{5,2} — precision and scale modifiers
email:string! — adds null: false constraint

Step 3: Write the Migration Body

Use the change method for reversible operations (Rails handles rollback automatically):

class CreatePosts < ActiveRecord::Migration[8.1]
  def change
    create_table :posts do |t|
      t.string :title, null: false
      t.text :body
      t.references :author, null: false, foreign_key: true
      t.datetime :published_at
      t.timestamps
    end

    add_index :posts, :published_at
    add_index :posts, :title
  end
end

For irreversible operations, use up/down:

class ChangePostsExcerptToText < ActiveRecord::Migration[8.1]
  def up
    change_column :posts, :excerpt, :text
  end

  def down
    change_column :posts, :excerpt, :string, limit: 500
  end
end

For mixed operations (some reversible, some not), use reversible inside change:

class AddStatusToPosts < ActiveRecord::Migration[8.1]
  def change
    add_column :posts, :status, :string, default: "draft"

    reversible do |dir|
      dir.up do
        execute <<~SQL
          UPDATE posts SET status = 'published' WHERE published_at IS NOT NULL
        SQL
      end
    end
  end
end

Step 4: Run and Verify

# Run pending migrations
bin/rails db:migrate

# Check it worked
bin/rails db:migrate:status

# If something's wrong with the LAST migration (before committing)
bin/rails db:rollback
# Fix the migration, then re-run
bin/rails db:migrate

Step 5: Commit schema.rb

Always commit db/schema.rb (or db/structure.sql) alongside your migration. This file is the authoritative schema snapshot.

Critical Gotchas

Always Index Foreign Keys

Every foreign key column needs an index. No exceptions.

# BAD — foreign key without index
t.bigint :author_id, null: false

# GOOD — use references (index included automatically)
t.references :author, null: false, foreign_key: true

# GOOD — manual column with explicit index
t.bigint :author_id, null: false, index: true

NOT NULL on Existing Tables Requires a Default

Adding a NOT NULL column to a table that already has rows will fail without a default value.

# BAD — fails if table has data
add_column :posts, :status, :string, null: false

# GOOD — provide a default
add_column :posts, :status, :string, null: false, default: "draft"

Never Reference Application Models in Migrations

Models change over time. Migrations are frozen in time. They will break.

# BAD — model may not exist or may have different validations later
class BackfillPostSlugs < ActiveRecord::Migration[8.1]
  def up
    Post.find_each { |p| p.update!(slug: p.title.parameterize) }
  end
end

# GOOD — use raw SQL
class BackfillPostSlugs < ActiveRecord::Migration[8.1]
  def up
    execute <<~SQL
      UPDATE posts SET slug = lower(replace(title, ' ', '-')) WHERE slug IS NULL
    SQL
  end
end

# ACCEPTABLE — inline class that won't change
class BackfillPostSlugs < ActiveRecord::Migration[8.1]
  class Post < ApplicationRecord; end

  def up
    Post.where(slug: nil).find_each do |post|
      post.update_column(:slug, post.title.parameterize)
    end
  end
end

Don't Use Dynamic Ruby Values as Defaults

# BAD — evaluates once at migration time, frozen forever
add_column :posts, :migrated_at, :datetime, default: Time.current

# GOOD — SQL function evaluates at row insertion time
add_column :posts, :migrated_at, :datetime, default: -> { "CURRENT_TIMESTAMP" }

Always Include Column Type in remove_column

Without the type, Rails can't reverse the migration.

# BAD — irreversible
remove_column :users, :legacy_field

# GOOD — reversible
remove_column :users, :legacy_field, :string

change_column Is NOT Reversible

Rails can't guess the old type. Always use up/down:

# BAD — will fail on rollback
def change
  change_column :posts, :body, :text
end

# GOOD
def up
  change_column :posts, :body, :text
end

def down
  change_column :posts, :body, :string
end

Reversible Operations Quick Reference

Auto-reversible in change:

create_table / drop_table (drop needs block + options)
add_column / remove_column (remove needs type)
add_index / remove_index (remove needs column + options)
add_reference / remove_reference
add_foreign_key / remove_foreign_key
add_timestamps / remove_timestamps
rename_column, rename_table, rename_index
change_column_default (needs from: and to:)
change_column_null
add_check_constraint / remove_check_constraint

Require up/down or reversible:

change_column (type changes)
execute (raw SQL)
Any data manipulation

Data Migrations

Small, Schema-Related Updates

Include them in the migration with reversible:

class AddStatusToPosts < ActiveRecord::Migration[8.1]
  def change
    add_column :posts, :status, :integer, default: 0, null: false

    reversible do |dir|
      dir.up do
        execute "UPDATE posts SET status = 1 WHERE published_at IS NOT NULL"
      end
    end
  end
end

Large Data Migrations

Don't put them in schema migrations. Use a rake task or the maintenance_tasks gem:

# lib/tasks/data_migrations.rake
namespace :data do
  desc "Backfill post statuses"
  task backfill_post_statuses: :environment do
    Post.where(status: nil).find_each(batch_size: 1000) do |post|
      post.update_column(:status, post.published_at? ? 1 : 0)
    end
  end
end

Why separate? Data migrations can be slow, may need to run at specific times, and have different rollback characteristics than schema changes.

Multi-Database Migrations

When the app uses multiple databases:

# Default database migrations go in db/migrate/
# Other databases use their own directories (configured in database.yml)

# Run specific database migrations
bin/rails db:migrate              # primary database
bin/rails db:migrate:animals      # "animals" database (example)

# Generate for a specific database
bin/rails generate migration CreateDogs name:string --database animals

Migration files for secondary databases live in their configured migrations_paths directory (e.g., db/animals_migrate/).

Commands Reference

# Generate
bin/rails generate migration AddNameToUsers name:string
bin/rails generate model Post title:string body:text

# Run
bin/rails db:migrate                      # Run all pending
bin/rails db:migrate VERSION=20240428...  # Migrate to specific version

# Rollback
bin/rails db:rollback                     # Undo last migration
bin/rails db:rollback STEP=3              # Undo last 3
bin/rails db:migrate:redo                 # Rollback + re-migrate last

# Status
bin/rails db:migrate:status               # Show up/down status of all

# Schema
bin/rails db:schema:dump                  # Regenerate schema.rb
bin/rails db:schema:load                  # Load schema (destructive!)

# Setup / Reset
bin/rails db:setup                        # Create + load schema + seed
bin/rails db:prepare                      # Idempotent setup
bin/rails db:reset                        # Drop + setup
bin/rails db:migrate:reset                # Drop + migrate from scratch

# Specific migration
bin/rails db:migrate:up VERSION=20240428...
bin/rails db:migrate:down VERSION=20240428...

# Environment
bin/rails db:migrate RAILS_ENV=test

When to Use This Skill

Creating new tables or modifying existing ones
Adding, removing, or renaming columns
Adding indexes or foreign keys
Changing column types or constraints
Writing data backfill migrations
Debugging migration errors or rollback issues
Setting up multi-database migrations
Understanding schema.rb vs structure.sql

For detailed column types, index patterns, UUID setup, check constraints, and advanced examples, see reference.md in this skill directory.

Agent Skills: Rails Migrations Expert

Install this agent skill to your local

Skill Files