Communitygithub.com

agents-inc/skills

BullMQ v5 を使用したジョブキュー、バックグラウンド処理、タスクスケジューリング

skills とは?

このスキルは、Redis 上で動作するジョブキューライブラリ BullMQ v5 を使用して、バックグラウンドジョブ処理、タスクスケジューリング、ワークフローオーケストレーションを実装するための包括的なガイドです。Queue(ジョブの追加)、Worker(ジョブの処理)、QueueEvents(グローバルイベントリスナー)、FlowProducer(親子ジョブツリー)の主要クラスをカバーし、特に v5 で必須となった connection オブジェクトの明示的な受け渡しや、Worker 向け ioredis 接続での maxRetriesPerRequest: null 設定が強調されています。また、非推奨 API に代わる upsertJobScheduler を使用した repeatable/cron ジョブの設定、レート制限、優先順位、グレースフルシャットダウン、サンドボックス化されたプロセッサなど、本番運用に必要なパターンとベストプラクティスを体系的に解説します。このスキルは Claude Code、Cursor、Codex など、Node.js と TypeScript をサポートする AI エージェントで活用でき、コード生成やリファクタリングの際に BullMQ の正しい使い方を支援します。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/api-queue-bullmq

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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 配送保証による信頼性の高いバックグラウンド処理を提供します。中核となる原則は次のとおりです:ジョブの生成とジョブの消費を分離 することで、作業が非同期で行われている間もアプリケーションの応答性を維持します。

中核原則:

  1. プロデューサーとコンシューマーは分離されている -- 任意のプロセスがキューにジョブを追加でき、任意の Worker がそれを処理できます。これにより、より多くの Worker を追加することで水平スケーリングが可能になります。
  2. ジョブは永続化される -- ジョブは Redis に存在するため、プロセスの再起動後も存続します。クラッシュした Worker のジョブは、他の Worker (または再起動後の同じ Worker) によって引き継がれます。
  3. at-least-once 配送 -- BullMQ はすべてのジョブが少なくとも 1 回処理されることを保証します。ストール後の (まれな) 重複処理を処理するには、冪等なプロセッサを使用します。
  4. リトライによるグレースフルな障害処理 -- attempts と backoff 戦略を設定することで、一時的な障害が自動的に解決されます。永続的に失敗したジョブは、検査のために failed セットに移動します。
  5. 各 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>

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

関連スキル