make:queue-batches-table — キュー バッチ テーブルを作成するマイグレーションを生成するコマンド

概要

項目	内容
カテゴリ	Artisan
掲載バージョン	Laravel 12 (PHP 8.4)
コマンド	php artisan make:queue-batches-table
関連API	queue:table, make:job, queue:failed, make:queue-table
追加されたバージョン	Laravel 9.0
戻り値	なし（マイグレーションファイルを生成）

TL;DR
ジョブバッチ機能を使うために必要な queue_batches テーブルを作るマイグレーションを自動生成します。

php artisan make:queue-batches-table

---

コマンド構文

php artisan make:queue-batches-table

引数

引数	型	必須	既定値	説明
—	—	—	—	なし

戻り値

0 (成功) もしくは例外 (FileAlreadyExistsException 等)

---

生成されるマイグレーション例

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateQueueBatchesTable extends Migration
{
    public function up()
    {
        Schema::create('queue_batches', function (Blueprint $table) {
            $table->id();
            $table->bigInteger('queueable_id')->nullable();
            $table->string('queueable_type')->nullable();
            $table->string('connection')->nullable();
            $table->string('queue')->nullable();
            $table->json('payload');
            $table->timestamp('created_at')->useCurrent();
            $table->timestamp('failed_at')->nullable();
            $table->timestamp('completed_at')->nullable();
        });
    }

    public function down()
    {
        Schema::dropIfExists('queue_batches');
    }
}

---

実務での使い方

1. マイグレーション生成

   php artisan make:queue-batches-table

2. マイグレーション実行

   php artisan migrate

3. ジョブクラス作成

   php artisan make:job ProcessLargeDataset

4. コントローラ／サービスからバッチを開始

   $batch = Queue::batch([
       ProcessLargeDataset::dispatch($data1),
       ProcessLargeDataset::dispatch($data2),
   ])->dispatch();

---

よくある落とし穴

症状	原因	対処
FileAlreadyExistsException	同名マイグレーションが既にある	ファイルを削除／リネームしてから再実行
テーブル名変更できない	コマンドは queue_batches 固定	マイグレーションを手動で編集
バッチが失敗時に failed_at が更新されない	ジョブ内の例外処理が不十分	try/catch で例外を再投げする
テーブルが作成されない	php artisan migrate を実行していない	php artisan migrate を実行

---

関連コマンド

コマンド	用途	選択のポイント
php artisan queue:table	失敗ジョブ用テーブル作成	失敗ジョブを追跡したいとき
php artisan make:queue-table	バッチ以外のジョブ用テーブル作成	バッチ以外のジョブを管理したいとき
php artisan make:job	ジョブクラス作成	バッチで処理するジョブを作るとき

---

テスト例（Pest）

it('creates queue_batches migration', function () {
    $this->artisan('make:queue-batches-table')
        ->expectsOutputToContain('created')
        ->assertExitCode(0);

    expect(glob(database_path('migrations/*_create_queue_batches_table.php')))->toBeArray()->toHaveCount(1);
});

---

参考リンク

• Laravel 12 Docs – Job Batches
• Laravel 12 Docs – Artisan Commands
• Queue Table Migration Source
• Make Queue Batches Table Command Source