BullMQ パターン
クイックガイド: BullMQ (v5.x) を、Redis 上でのバックグラウンドジョブ処理、タスクスケジューリング、ワークフローオーケストレーションに使用します。主要クラス:
Queue(ジョブ追加)、Worker(ジョブ処理)、QueueEvents(グローバルイベントリスナー)、FlowProducer(親子ジョブツリー)。すべてのコンストラクタにconnectionオブジェクトを必ず渡します (v5 で必須)。Worker 用の ioredis 接続にはmaxRetriesPerRequest: nullを設定します。繰り返し/cron ジョブにはupsertJobSchedulerを使用します (非推奨の repeatable API の代替)。QueueScheduler は v4 で削除されました。その責務は Worker によって自動的に処理されます。
<critical_requirements>
重要: このスキルを使用する前に
すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります (kebab-case、名前付きエクスポート、インポート順序、
import type、名前付き定数)
(すべての Queue、Worker、QueueEvents、FlowProducer コンストラクタに connection オブジェクトを必ず渡さなければなりません -- BullMQ v5 は connection がないとエラーをスローします)
(Worker が使用する ioredis 接続には maxRetriesPerRequest: null を必ず設定しなければなりません -- BullMQ は無限リトライを必要とし、この設定がないとエラーをスローします)
(SIGTERM/SIGINT で graceful shutdown のために await worker.close() を必ず呼び出さなければなりません -- これがないと、処理中のジョブが stalled 状態になります)
(繰り返し/cron ジョブには upsertJobScheduler を必ず使用しなければなりません -- 古い queue.add の repeat オプションは v5.16.0 以降非推奨です)
</critical_requirements>
例
- コアパターン -- Queue のセットアップ、Worker 処理、ジョブオプション、接続ファクトリ、グレースフルシャットダウン、型付きジョブ
- 高度なパターン -- FlowProducer、レート制限、ジョブスケジューリング、QueueEvents、並行性、サンドボックス化されたプロセッサ
追加リソース:
- reference.md -- 決定フレームワーク、ジョブオプションリファレンス、アンチパターン、プロダクションチェックリスト
自動検出: BullMQ, bullmq, Queue, Worker, QueueEvents, FlowProducer, job queue, background job, worker process, job scheduler, upsertJobScheduler, rate limiter, job priority, job delay, sandboxed processor, repeatable job, cron job, flow producer, parent child jobs
使用すべき場合:
- バックグラウンド処理 (メール送信、画像処理、PDF生成)
- スケジュール/cron ジョブ (夜間レポート、定期的なクリーンアップ)
- 親子ジョブ依存関係によるワークフローオーケストレーション (FlowProducer)
- レート制限付き API 消費 (送信リクエストのスロットリング)
- 優先順位ベースのジョブ処理 (一括操作の前に緊急ジョブ)
- CPU 負荷の高い作業を複数のワーカーまたはマシンに分散
カバーする主要パターン:
- 型付きジョブデータと戻り値を使用した Queue と Worker のセットアップ
- Worker 向け
maxRetriesPerRequest: nullを使用した接続ファクトリ - ジョブオプション: delay、priority、attempts、backoff、removeOnComplete/Fail
- プロセスシグナルによる
worker.close()を使用したグレースフルシャットダウン - 依存関係追跡を使用した親子ジョブツリーの FlowProducer
- 繰り返し/cron ジョブ用のジョブスケジューラ (
upsertJobScheduler) - レート制限 (グローバルリミッターと手動
Worker.RateLimitError) - 並行性制御 (Worker ごとのローカルとグローバル)
- すべてのワーカーにわたるグローバルイベント監視のための QueueEvents
- CPU 負荷の高い作業のためのサンドボックス化されたプロセッサ
使用すべきでない場合:
- 単純なインプロセスタイマーまたは
setTimeout(永続化不要) - 永続化なしのリアルタイム pub/sub メッセージング (pub/sub ソリューションを使用)
- リクエスト-レスポンスサイクル内で同期的に処理する必要があるデータ
- 永続化、リトライ、スケジューリングが不要なキュー
哲学
BullMQ は Node.js 向けの Redis バックアップジョブキュー であり、at-least-once 配送保証による信頼性の高いバックグラウンド処理を提供します。中核となる原則は次のとおりです:ジョブの生成とジョブの消費を分離 することで、作業が非同期で行われている間もアプリケーションの応答性を維持します。
中核原則:
- プロデューサーとコンシューマーは分離されている -- 任意のプロセスがキューにジョブを追加でき、任意の Worker がそれを処理できます。これにより、より多くの Worker を追加することで水平スケーリングが可能になります。
- ジョブは永続化される -- ジョブは Redis に存在するため、プロセスの再起動後も存続します。クラッシュした Worker のジョブは、他の Worker (または再起動後の同じ Worker) によって引き継がれます。
- at-least-once 配送 -- BullMQ はすべてのジョブが少なくとも 1 回処理されることを保証します。ストール後の (まれな) 重複処理を処理するには、冪等なプロセッサを使用します。
- リトライによるグレースフルな障害処理 --
attemptsとbackoff戦略を設定することで、一時的な障害が自動的に解決されます。永続的に失敗したジョブは、検査のために failed セットに移動します。 - 各 Queue/Worker/QueueEvents は独自の接続を必要とする -- BullMQ は内部で接続状態を管理します。複数の BullMQ クラス間で単一の ioredis インスタンスを共有しないでください (プロデューサーとしてのみ機能する Queue を除く)。
コアパターン
パターン 1: 接続ファクトリ
BullMQ v5 では、すべてのコンストラクタに明示的な Redis 接続が必要です。Worker は maxRetriesPerRequest: null を必要とし、ioredis が諦める代わりに無期限にリトライするようにします。
import Redis from "ioredis";
function createBullMQConnection(): Redis {
const url = process.env.REDIS_URL;
if (!url) throw new Error("REDIS_URL is required");
return new Redis(url, { maxRetriesPerRequest: null });
}
export { createBullMQConnection };
なぜ良いか: maxRetriesPerRequest: null は BullMQ の要件を満たし、ファクトリは一貫した設定を保証し、環境変数はコードから資格情報を除外します
// 悪い例 -- maxRetriesPerRequest が欠落
const redis = new Redis("redis://localhost:6379");
const worker = new Worker("emails", processor, { connection: redis });
// BullMQ がスロー: "maxRetriesPerRequest must be null"
なぜ悪いか: BullMQ は Worker 接続に無限リトライを必要とし、null がないと起動時にスローします
完全なプロデューサー対コンシューマー分離を含む接続ファクトリについては、examples/core.md を参照してください。
パターン 2: Queue と Worker のセットアップ
Queue がジョブを追加し、Worker が処理します。両方とも、型安全なジョブデータと戻り値のために TypeScript ジェネリクスを受け入れます。
import { Queue, Worker, type Job } from "bullmq";
interface EmailJobData {
to: string;
subject: string;
body: string;
}
const QUEUE_NAME = "emails";
const emailQueue = new Queue<EmailJobData>(QUEUE_NAME, {
connection: createBullMQConnection(),
});
const emailWorker = new Worker<EmailJobData>(
QUEUE_NAME,
async (job: Job<EmailJobData>) => {
await sendEmail(job.data.to, job.data.subject, job.data.body);
},
{ connection: createBullMQConnection() },
);
なぜ良いか: ジェネリクスは job.data の型安全性を強制し、Queue と Worker に別々の接続、キュー名に名前付き定数を使用
イベント、エラーハンドリング、型付き戻り値を含む完全なセットアップについては、examples/core.md を参照してください。
パターン 3: ジョブオプション
遅延、優先度、リトライ、バックオフ、自動削除などのオプションでジョブの動作を制御します。
const MAX_ATTEMPTS = 5;
const BACKOFF_DELAY_MS = 1000;
const DELAY_MS = 60_000;
const KEEP_COMPLETED_COUNT = 100;
await emailQueue.add(
"send-welcome",
{ to: "[email protected]", subject: "Welcome", body: "..." },
{
delay: DELAY_MS,
priority: 1, // 1 = 最高、数値が大きいほど優先度が低い
attempts: MAX_ATTEMPTS,
backoff: { type: "exponential", delay: BACKOFF_DELAY_MS },
removeOnComplete: { count: KEEP_COMPLETED_COUNT },
removeOnFail: false,
},
);
なぜ良いか: すべての数値に名前付き定数、一時的な障害に対する指数バックオフ、removeOnComplete による件数指定は Redis メモリの無制限な増加を防ぎ、removeOnFail: false はデバッグ用に失敗したジョブを保持
defaultJobOptions、addBulk、LIFO パターンについては、examples/core.md を参照してください。
パターン 4: グレースフルシャットダウン
プロセスシグナルで worker.close() を呼び出し、終了前に処理中のジョブを完了させます。これがないと、ジョブは stalled 状態になり、他の Worker によって再処理されます。
async function shutdown(workers: Worker[]): Promise<void> {
await Promise.all(workers.map((w) => w.close()));
process.exit(0);
}
process.on("SIGTERM", () => shutdown([emailWorker]));
process.on("SIGINT", () => shutdown([emailWorker]));
なぜ良いか: close() は新しいジョブの受け入れを停止し、処理中のジョブが完了するのを待ちます。Promise.all は複数のワーカーを処理し、シグナルハンドラは SIGTERM と SIGINT の両方をカバーします
落とし穴: worker.close() には組み込みのタイムアウトがありません。プロセッサがハングすると、シャットダウンもハングします。必要に応じて、独自のタイムアウトでラップしてください。
タイムアウトパターン付きシャットダウンについては、examples/core.md を参照してください。
パターン 5: FlowProducer (親子ジョブ)
FlowProducer は、親ジョブがすべての子ジョブの完了を待つジョブツリーを作成します。ツリー全体がアトミックに追加されます。
import { FlowProducer } from "bullmq";
const flowProducer = new FlowProducer({ connection: createBullMQConnection() });
await flowProducer.add({
name: "publish-video",
queueName: "videos",
children: [
{ name: "extract-audio", queueName: "media", data: { videoId: "abc" } },
{
name: "generate-thumbnail",
queueName: "media",
data: { videoId: "abc" },
},
{
name: "transcode",
queueName: "media",
data: { videoId: "abc", format: "mp4" },
},
],
});
なぜ良いか: 親はすべての子が完了するまで待機し、アトミックな追加 (すべてか無か)、子は異なるキューに配置可能、親プロセッサは job.getChildrenValues() で子の結果にアクセス可能
子の値へのアクセスとネストされたフローについては、examples/advanced.md を参照してください。
パターン 6: ジョブスケジューラ (Repeatable/Cron ジョブ)
繰り返しジョブには upsertJobScheduler (v5.16.0+) を使用します。非推奨の repeat オプションの代替です。
const REPORT_INTERVAL_MS = 3_600_000; // 1時間
// 固定間隔
await emailQueue.upsertJobScheduler(
"hourly-digest",
{ every: REPORT_INTERVAL_MS },
{
name: "send-digest",
data: { type: "hourly" },
},
);
// Cron 式 -- 毎日 3:15 AM
await emailQueue.upsertJobScheduler(
"nightly-cleanup",
{ pattern: "0 15 3 * * *" },
{
name: "cleanup",
data: { type: "nightly" },
opts: { removeOnComplete: true },
},
);
なぜ良いか: upsertJobScheduler は冪等 (起動のたびに安全に呼び出せる)、テンプレートは生成される各ジョブが継承するジョブ名/データ/opts を定義、pattern による cron 構文
落とし穴: every 間隔は upsertJobScheduler を呼び出した時刻ではなく、時計に合わせられます。2000ms の間隔は 0秒、2秒、4秒... に起動します。
スケジューラの削除とアクティブなスケジューラの一覧表示については、examples/advanced.md を参照してください。
パターン 7: レート制限
Worker が時間枠あたりに処理するジョブ数を制限します。リミッターは同じキュー上のすべての Worker にわたってグローバルです。
const RATE_LIMIT_MAX = 10;
const RATE_LIMIT_DURATION_MS = 1000;
const worker = new Worker("api-calls", processor, {
connection: createBullMQConnection(),
limiter: { max: RATE_LIMIT_MAX, duration: RATE_LIMIT_DURATION_MS },
});
なぜ良いか: グローバルレート制限 (この設定の 10 個の Worker でも合計で最大 10 ジョブ/秒を処理)、制限値に名前付き定数
外部 API 応答に基づく動的なレート制限については、worker.rateLimit(duration) + throw Worker.RateLimitError() を使用します。examples/advanced.md を参照してください。
パターン 8: グローバル監視のための QueueEvents
QueueEvents は Redis Pub/Sub ではなく Redis Streams を使用するため、再接続時でもイベントが信頼性があります。専用の接続が必要です。
import { QueueEvents } from "bullmq";
const queueEvents = new QueueEvents(QUEUE_NAME, {
connection: createBullMQConnection(),
});
queueEvents.on("completed", ({ jobId, returnvalue }) => {
console.log(`Job ${jobId} completed with: ${returnvalue}`);
});
queueEvents.on("failed", ({ jobId, failedReason }) => {
console.error(`Job ${jobId} failed: ${failedReason}`);
});
なぜ良いか: 単一のリスナーからキュー上のすべての Worker を監視、Redis Streams による信頼性の高い配信、必須の専用接続
進捗追跡と特定のジョブ完了の待機については、examples/advanced.md を参照してください。
パフォーマンス最適化
- 並行性 -- Worker オプションで
concurrencyを設定すると、単一の Worker インスタンス内で複数のジョブを並行して処理できます:{ concurrency: 10 }。I/O バウンドの作業にのみ効果的です。CPU バウンドの作業はイベントループをブロックし、ストールジョブの原因になります。代わりにサンドボックス化されたプロセッサを使用してください。 - サンドボックス化されたプロセッサ -- Worker コンストラクタに関数の代わりにファイルパスを渡すと、プロセッサが別のプロセス (または
useWorkerThreads: trueでワーカースレッド) で実行されます。CPU 負荷の高い作業がロックの更新をブロックするのを防ぎます。 - addBulk --
queue.add()をループで呼び出す代わりに、queue.addBulk([...])を使用して、1 回の Redis ラウンドトリップで多くのジョブを追加します。 - removeOnComplete/Fail -- 自動削除を設定して、Redis メモリの無制限な増加を防ぎます。
{ count: N }を使用して、デバッグ用に最新の N 個のジョブを保持します。 - 別々の接続 -- プロデューサー (Queue) は接続を共有できます。Worker と QueueEvents は、ブロッキング Redis コマンドのため、それぞれ独自の接続が必要です。
<decision_framework>
決定フレームワーク
BullMQ を使用すべき場合
バックグラウンドジョブ処理が必要ですか?
|-- NO -> BullMQ を使用しない
+-- YES -> 永続化、リトライ、またはスケジューリングが必要ですか?
|-- NO -> シンプルなインプロセスキューまたは setTimeout で十分な場合がある
+-- YES -> 親子ジョブの依存関係が必要ですか?
|-- YES -> FlowProducer を使用した BullMQ
+-- NO -> レート制限または優先順位が必要ですか?
|-- YES -> limiter/priority オプションを使用した BullMQ
+-- NO -> 基本的な Queue + Worker を使用した BullMQ
どのジョブパターンを使用すべきか?
どのようなジョブスケジューリングが必要ですか?
|-- 1回限りの遅延ジョブ -> delay オプション付き queue.add()
|-- 固定間隔の繰り返しジョブ -> every オプション付き upsertJobScheduler
|-- Cron スケジュールジョブ -> pattern オプション付き upsertJobScheduler
+-- 親子依存関係 -> FlowProducer の add
</decision_framework>