make:queue-failed-table — 失敗したジョブを保存するテーブルを作成するコマンド
artisan
2026.03.16
queue:failed-table は、失敗したジョブを永続化するためのマイグレーションファイルを生成します。正しいコマンド名 ：php artisan queue:failed-tablemake:queue-failed-table は存在しません）
実装対象 項目 内容 コマンド php artisan queue:failed-table対象ファイル database/migrations/*_create_failed_jobs_table.phpテーブル名 デフォルトは failed_jobs（config/queue.php の failed → database → table で変更可）
実行手順 # 1. マイグレーションファイルを作成
php artisan queue:failed-table
# 2. マイグレーションを実行
php artisan migrate
マイグレーション例 <?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class CreateFailedJobsTable extends Migration
{
public function up()
{
Schema::create('failed_jobs', function (Blueprint $table) {
$table->bigIncrements('id');
$table->text('connection');
$table->text('queue');
$table->text('payload');
$table->text('exception');
$table->timestamp('failed_at')
->useCurrent()
->index();
});
}
public function down()
{
Schema::dropIfExists('failed_jobs');
}
}
テーブル名のカスタマイズ // config/queue.php
'failed' => [
'database' => [
'table' => 'my_failed_jobs',
],
],
php artisan queue:failed-table を実行した後、migrate を走らせると my_failed_jobs テーブルが作成されます。
実務上の注意 項目 推奨設定/手順 マイグレーションの重複生成 コマンドを複数回実行しない。必要ならテーブル名を変更 古いレコード削除 php artisan queue:flush で定期的にクリア通知 config/queue.php の failed_job_reporter でメール/Slack 通知を設定機密情報の扱い payload にセンシティブデータを入れない（ジョブクラスで暗号化等を行う）インデックス failed_at にインデックスが付いているので検索が高速
主要コマンドとの比較 コマンド 役割 queue:failed失敗ジョブ一覧表示 queue:retry {id}指定ジョブを再試行 queue:flush失敗ジョブテーブルを空に queue:failed-table失敗ジョブ用マイグレーション生成
変更履歴 バージョン 変更点 5.8.x queue:failed-table コマンド登場6.x‑12.x 仕様変更なし、テーブル名は failed_jobs 12.x 同上（config/queue.php でテーブル名カスタマイズ可能）
コード例（ジョブ失敗時の確認） # 1. 失敗テーブル用マイグレーション作成
php artisan queue:failed-table
# 2. マイグレーション実行
php artisan migrate
# 3. 失敗ジョブの確認
php artisan queue:failed
テストコード（Pest） <?php
use Illuminate\Support\Facades\Artisan;
use Illuminate\Support\Facades\DB;
it('creates a migration for failed_jobs table', function () {
// 1. コマンド実行
Artisan::call('queue:failed-table');
// 2. マイグレーションファイルが作成されているか確認
$files = collect(scandir(database_path('migrations')))
->filter(fn ($file) => str_contains($file, 'create_failed_jobs_table.php'));
expect($files->count())->toBe(1);
// 3. マイグレーションを実行
Artisan::call('migrate', ['--path' => database_path('migrations/' . $files->first())]);
// 4. テーブルが作成されたか確認
expect(DB::connection()->getDoctrineSchemaManager()->tablesExist(['failed_jobs']))->toBeTrue();
});
トラブルシューティング 問題 原因 対処 マイグレーションエラー SQLSTATE[42S01] 同一テーブル名のマイグレーションが重複 ファイル名・テーブル名をユニークに変更 失敗ジョブが failed_jobs に記録されない failed 接続設定が不正config/queue.php の failed → database を確認失敗ジョブが大量化しスケールが遅い 古いレコードが残っている queue:flush でクリア、インデックスを再構築
注 php artisan migrate を走らせてください。
まとめ php artisan queue:failed-table は、ジョブ失敗時に必要な failed_jobs テーブルを手軽に作成できるコマンドです。実務ではマイグレーションの重複に注意し、古い失敗ジョブを定期的に削除してテーブルサイズを管理するとともに、payload に機密情報を入れない設計が重要です。
