- カテゴリ：artisan
- 掲載バージョン：Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド：
php artisan queue:clear - 関連：queue:flush, queue:prune, queue:restart, queue:work, queue:listen
- 変更履歴：Laravel 8.0 で追加、以降は非推奨・削除は無し
要点（TL;DR）
- データベースキューの未処理ジョブを一括削除する
- 最短コマンド：
php artisan queue:clear - よくある落とし穴
- データベース以外のドライバでは動作しない
- ワーカーが走っていると競合が起きる
- ジョブのロック情報は残る
概要
queue:clear は、Laravel の データベースキュー で未処理ジョブを全て削除します。
実務では、マイグレーション前に古いジョブをクリアしたり、デバッグでジョブを一掃したいときに使われます。
注意点としては、ワーカーが同時にジョブを取得している場合に削除されてしまう可能性がある点です。
構文 / シグネチャ
// php artisan queue:clear {connection?} {--queue=}
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
| connection | string | 〇 | database | クリア対象のキュードライバ。データベースドライバのみサポート。 |
| –queue | string | × | * | クリアしたいジョブの名前（複数可）。* で全ジョブ。 |
戻り値：void（実行結果はコンソールに出力される）
例外：
- ドライバがデータベース以外の場合は
RuntimeExceptionを投げる。 - クリアしたジョブ数をカウントして表示。
使用例
最小例
php artisan queue:clear
実務例
# マイグレーション前に古いジョブを削除
php artisan queue:clear database
# 特定のジョブのみ削除
php artisan queue:clear database --queue=emails
よくある落とし穴・注意
- ドライバ制限：
syncやredisなどデータベース以外のドライバではRuntimeExceptionが発生。 - ワーカーの競合：ワーカーが同時にジョブを取得していると、クリア後も再取得される可能性。
- ロック情報の残存：
queue:clearはジョブ行のみを削除するため、ロックテーブルに残る情報が混乱を招くことがある。
代替・関連APIとの比較
| API | 主な用途 | 選定基準 |
|---|---|---|
queue:flush | 全てのキューからジョブを一括削除 | 全接続を対象にしたいとき |
queue:prune | 指定期間経過したジョブを削除 | 古いジョブをクリーンアップしたいとき |
queue:restart | ワーカーを再起動 | デプロイ時にワーカーをリスタートしたいとき |
queue:work / queue:listen | ジョブを実行 | 実際にジョブを処理したいとき |
テスト例（Pest）
use Illuminate\Support\Facades\Queue;
it('clears all jobs from database queue', function () {
Queue::connection('database')->push(new TestJob);
// 前提：ジョブが1件ある
expect(Queue::connection('database')->size())->toBe(1);
$this->artisan('queue:clear')
->expectsOutput('1 jobs cleared.')
->assertExitCode(0);
// 結果：ジョブが削除される
expect(Queue::connection('database')->size())->toBe(0);
});
トラブルシュート（エラー別）
| 症状 / エラー | 原因 | 対処 |
|---|---|---|
RuntimeException: Connection "sync" is not a database queue driver. | クリア対象がデータベース以外 | --connection=database を指定、あるいは queue:flush を使用 |
Connection closed before full data received. | ネットワーク障害（Redis 等） | データベース接続を確認、queue:clear には適用不可 |
Job not found | 既にワーカーがジョブを取得 | ワーカーを停止してから再実行 |
