こんにちは、かつコーチです。
マイグレーションを実行したら、途中で止まって動かなくなった経験はありませんか。
私は開発中に何度もこの状況に陥り、原因が分からず焦った経験があります。
この記事では、マイグレーション失敗時の代表的な症状と、実際に私が遭遇したエラーを使った対処法を解説します。
読み終える頃には、慌てずにマイグレーションのトラブルへ対応できるようになります。
症状の再現：マイグレーションが失敗する典型パターン
カラム重複によるエラー
すでに存在するカラムを追加しようとすると、マイグレーションは失敗します。
一度実行に失敗すると、データベースとマイグレーションファイルの状態がズレてしまいます。
途中で処理が止まる不整合
複数のマイグレーションファイルを一気に実行した際、途中の1つが失敗すると、それ以降は実行されません。
結果として「一部だけ反映された中途半端な状態」になり、次に何を実行すればいいか分からなくなります。
実装手順：状況確認から復旧まで
手順1：マイグレーションの状態を確認する
まずはdb:migrate:statusで、どこまで反映されているかを確認します。
bin/rails db:migrate:status
database: myapp_development
Status Migration ID Migration Name
--------------------------------------------------
up 20260810120000 Create articles
down 20260812093000 Add category to articles
downと表示されている行が、まだ実行されていないマイグレーションです。
手順2：db:rollbackで巻き戻す
直前のマイグレーションを取り消したい場合は、db:rollbackを使います。
bin/rails db:rollback
複数世代を一度に戻したい場合は、STEPオプションで戻す数を指定します。
bin/rails db:rollback STEP=2
手順3：マイグレーションファイルを修正して再実行する
エラーの原因になったマイグレーションファイルを修正したら、再度db:migrateを実行します。
bin/rails db:migrate
よくあるつまずきポイント・エラー対処
Before/After：カラム重複エラー
私が実際に遭遇したのは、すでに存在するcategoryカラムをもう一度追加しようとしたケースです。
❌Before：既存カラムを重複して追加しようとした状態
# db/migrate/20260812093000_add_category_to_articles.rb
class AddCategoryToArticles < ActiveRecord::Migration[8.0]
def change
add_column :articles, :category, :string
end
end
bin/rails db:migrate
StandardError: An error has occurred, this and all later migrations canceled:
SQLite3::SQLException: duplicate column name: category
過去に一度手動でカラムを追加していたことを忘れ、同じ内容のマイグレーションを作ってしまっていました。
このエラーで15分ほど、何が起きているのか理解できずに固まってしまいました。
✅After：ロールバックしてから状況を整理する
まず、失敗したマイグレーションを一度ロールバックします。
bin/rails db:rollback
続いて、schema.rbを確認し、実際にcategoryカラムが存在するかを目視で確認しました。
# db/schema.rb（抜粋）
create_table "articles", force: :cascade do |t|
t.string "title"
t.string "category"
end
すでにcategoryカラムが存在していたため、該当のマイグレーションファイル自体を削除し、db:migrate:statusで整合性を確認して解決しました。
Before/After：スキーマの不整合によるエラー
チーム開発でブランチを切り替えた際、schema.rbのバージョンとデータベースの実態がズレることがあります。
❌Before：schema.rbとデータベースの状態が一致しない
bin/rails db:migrate
ActiveRecord::NoEnvironmentInSchemaError:
Environment data not found in the schema. To resolve this issue, run:
bin/rails db:environment:set RAILS_ENV=development
他のブランチで作業した後、db:schema:loadを実行せずにマイグレーションを走らせたことが原因でした。
✅After：schema:loadで一旦揃えてから再実行する
bin/rails db:schema:load
bin/rails db:migrate
db:schema:loadでschema.rbの内容をデータベースに反映し直すことで、状態を揃えてから改めてマイグレーションを実行します。
チーム開発でブランチを切り替えるたびに、この手順を踏むことが安全策になります。
まとめ
この記事のポイント
- マイグレーションが失敗したら、まず
db:migrate:statusで状態を確認する db:rollbackで直前の変更を取り消してから、原因を調査する- カラム重複エラーは、
schema.rbを見て実際の状態と照合するのが近道 - ブランチ切り替え時のスキーマ不整合は
db:schema:loadで揃える
次に読むべき記事
マイグレーション以外のよくあるエラーも知りたい方は「Railsでよく出るエラーと解決法まとめ」を参考にしてください。rails consoleでデータベースの中身を直接確認する方法は「rails consoleを使いこなすデバッグ術」で解説しています。
タグ: Ruby on Rails, 中級者向け, エラー解決