Laravel Artisan コマンド：migrate:refresh
一言概要
データベースを一旦全リセットし、再度マイグレーションを実行する。
- カテゴリ: artisan
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
php artisan migrate:refresh - 関連:
migrate:reset,migrate,db:seed,migrate:rollback,migrate:fresh - 変更履歴: Laravel 5.4 で追加、以降は非推奨動作はなく安定。
要点（TL;DR）
- 使う場面: 開発中にテーブル構造を完全にリセットしたい時。
- 最低限の使い方:
php artisan migrate:refresh - よくある罠
- 本番環境で実行するとデータ損失。
--seedを付け忘れるとシーダーが走らない。- マイグレーションが破損していると失敗する。
概要
migrate:refresh は migrate:reset + migrate（必要なら db:seed）を一括で実行します。
データベースを初期化し、最新のマイグレーションを適用したい開発環境で頻繁に使用されます。
実行環境
| 環境 | 使い方 | 注意点 |
|---|---|---|
| 開発 | 変更後のテーブル構造を確認する際 | データは必ず無い（開発用） |
| CI | テスト前にテーブルをリセット | テストスクリプトで --seed を付けるとデータセットが自動で作成 |
| 本番 | 使用しない | データ損失が発生するため、--force も付けずに走らせない |
スケジューラ（Laravel Scheduler）
// app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
// 毎日午前2時にテスト環境用にリフレッシュ
$schedule->command('migrate:refresh --seed')
->dailyAt('02:00')
->onOneServer()
->withoutOverlapping();
}
構文 / シグネチャ
php artisan migrate:refresh [options] [--path=PATH] [--realpath] [--database=DATABASE] [--force] [--seed] [--seeder=SEEDER] [--pretend] [--step]
引数
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
--path |
string | いいえ | null |
実行対象のマイグレーションファイルパス（相対） |
--realpath |
bool | いいえ | false |
--path に実際のファイルパスを指定 |
--database |
string | いいえ | null |
使用するデータベース接続名 |
--force |
bool | いいえ | false |
本番環境での実行を許可 |
--seed |
bool | いいえ | false |
db:seed を実行 |
--seeder |
string | いいえ | null |
カスタムシーダークラスを指定 |
--pretend |
bool | いいえ | false |
SQL を実行せずに表示 |
--step |
int | いいえ | 未指定（全件） | 直近N件だけロールバック＆再実行する件数を指定（例: --step=5）。省略時は全マイグレーションが対象 |
戻り値
0（成功）または 1（失敗）を返す。Laravel は内部でコマンドを実行し、終了コードで結果を示す。
例外 / 副作用
- データ損失：すべてのテーブルが削除されるため、必ずバックアップや環境を確認。
- トランザクション：マイグレーションは一括で実行され、途中で失敗すると全体がロールバックされる。
- ログ：
--pretendを付けると、実際の SQL がコンソールに表示されるが、何も書き込まない。
使用例
| コマンド | 目的 | 結果 |
|---|---|---|
php artisan migrate:refresh |
テーブルをリセットして再適用 | Migrated 12 migrations と表示 |
php artisan migrate:refresh --seed |
リフレッシュ後に seed も走らせる | Migrated 12 migrations + Seeded 12 tables |
# 例：ローカルでの最小限の実行
$ php artisan migrate:refresh
# 例：CI でリフレッシュ + seed
$ php artisan migrate:refresh --seed
よくある落とし穴・注意
| 症状 / エラー | 原因 | 対処 |
|---|---|---|
SQLSTATE[42S02]: Base table or view not found |
マイグレーションが壊れている、あるいは古い | php artisan migrate:reset でクリーン後に再実行 |
Connection refused |
データベース接続情報が不正 | .env の DB_* 設定を確認 |
Cannot find class |
マイグレーションファイルのクラス名とファイル名が一致しない | ファイル名とクラス名を統一 |
代替 / 関連 API
| コマンド | 機能 | 使う場面 |
|---|---|---|
migrate:reset |
すべてのマイグレーションをロールバック（再実行はしない） | 「ロールバックだけ」必要 |
migrate:fresh |
全テーブルをDBから直接削除してマイグレーションを実行 | 一気に初期化 が必要、down()の実装に依存したくない |
migrate:rollback |
直近の1ステップだけロールバック | 最近の変更だけ戻したい |
migrate:status |
各マイグレーションの適用状況を一覧表示 | 実行前に現在の状態を確認したい |
migrate:refresh は migrate:reset + migrate を一括で実行できるため、「一気にリセット＋再適用」 が必要なときに最適です。
migrate:freshとmigrate:refreshの違い
どちらも「テーブルを空にしてマイグレーションを再実行する」点は同じですが、内部的な仕組みが異なります。
migrate:refresh：各マイグレーションのdown()を呼び出してロールバックしてから、up()を再実行する。down()が正しく実装されていないマイグレーションがあると失敗する。migrate:fresh：down()を呼ばず、DBのテーブルを直接すべて削除（DROP）してからマイグレーションを実行する。down()の実装に依存しないため、down()が未実装・不完全な場合でも動作する。
そのため、迷ったら基本的には migrate:fresh の方がシンプルで失敗しにくく、migrate:refresh は「ロールバック処理（down()）自体を検証したい」場合に選ぶのが実務的な使い分けです。
テスト例（Pest）
it('refreshes migrations and seeds', function () {
// DB のテーブルを全て削除し、再作成して seed を走らせる
$this->artisan('migrate:refresh', ['--seed' => true]);
// 例: users テーブルが存在し、seed が走ったことを確認
expect(DB::table('users')->exists())->toBeTrue();
expect(DB::table('users')->count())->toBeGreaterThan(0);
});
トラブルシュート（エラー別）
| 症状 / エラー | 原因 | 対処 |
|---|---|---|
SQLSTATE[42S02]: Base table or view not found |
マイグレーションが壊れている、あるいは古い | php artisan migrate:reset でクリーン後に再実行 |
Connection refused |
データベース接続情報が不正 | .env の DB_* 設定を確認 |
Cannot find class |
マイグレーションファイルのクラス名とファイル名が一致しない | ファイル名とクラス名を統一 |
よくある質問（FAQ）
Q. migrate:refreshとmigrate:freshはどちらを使えばいい？
A. 用途に強いこだわりがなければ migrate:fresh の方が単純で、down()メソッドの実装ミスに影響されず確実に初期化できます。migrate:refresh はdown()のロールバック処理自体をテストしたい場合や、Laravel 5.4以前からの慣習で使われているケースが中心です。
Q. –stepオプションで一部のマイグレーションだけリフレッシュできる？
A. できます。php artisan migrate:refresh --step=3 のように指定すると、直近3件のマイグレーションだけロールバック＆再実行されます。省略時はすべてのマイグレーションが対象です。
Q. 本番環境でどうしても実行する必要がある場合は？
A. 基本的に非推奨です。どうしても必要な場合は事前にDBの完全バックアップを取得し、--forceオプションを付けたうえで、メンテナンスモード（php artisan down）にしてから実行してください。