migrate:refresh — マイグレーションをすべてリフレッシュして再実行するコマンド

Laravel Artisan コマンド：migrate:refresh
関連記事

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`	bool	いいえ	`false`	1件ずつロールバック（ロールバック時）

戻り値

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`	すべてのテーブルを削除してマイグレーションを実行	一気に初期化が必要
`migrate:rollback`	直近の1ステップだけロールバック	最近の変更だけ戻したい

migrate:refresh は reset + migrate を一括で実行できるため、「一気にリセット＋再適用」 が必要なときに最適です。

テスト例（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`	マイグレーションファイルのクラス名とファイル名が一致しない	ファイル名とクラス名を統一