bull-mq

BullMQ — Redis-Based Job Queue for Node.js

Overview

BullMQ moves slow or unreliable work out of the request path. A Queue adds jobs, one or more Workers (usually separate processes) take them, and QueueEvents observes what happened. Jobs survive restarts because they live in Redis. Features: delays, priorities, retries with backoff, global rate limits, deduplication, job schedulers for recurring work, and FlowProducer for trees of dependent jobs.

Version notes (checked October 2026, bullmq 6.3.x):

• BullMQ 6 (July 2026) adds pluggable backends: Redis stays the default, PostgreSQL is optional via createPostgresBackend.
• ioredis is no longer a dependency. Install it yourself: npm install bullmq ioredis. The redis package (node-redis) and Bun's built-in Redis client also work through adapters, but ioredis is what BullMQ creates by default.
• Legacy repeatable jobs are gone. add(name, data, { repeat }), getRepeatableJobs() and removeRepeatable() were replaced by job schedulers (upsertJobScheduler). In a test against 6.3.11 a leftover repeat option was accepted without error but created no schedule; the job simply ran once.
• QueueScheduler was removed in BullMQ 2; delayed jobs, retries and stalled-job recovery work without it. Old code that imports it will not compile.
• Queue#client, Worker#blockingClient and the debounce option are removed (use deduplication), and queue.resume() must be awaited.

Instructions

Queue, worker and retries

import { Queue, Worker } from "bullmq";
import IORedis from "ioredis";

// Workers need maxRetriesPerRequest: null so Redis hiccups do not crash blocking commands
const connection = new IORedis(process.env.REDIS_URL ?? "redis://127.0.0.1:6379", { maxRetriesPerRequest: null });

export const emailQueue = new Queue("email", { connection });

await emailQueue.add(
  "welcome",
  { to: "[email protected]", template: "welcome" },
  {
    priority: 1,                                  // lower number = higher priority
    attempts: 5,                                  // total tries, including the first
    backoff: { type: "exponential", delay: 2000 },
    removeOnComplete: { count: 1000 },            // keep the last 1000 finished jobs
    removeOnFail: { age: 7 * 24 * 3600 },         // keep failures for 7 days
  },
);

await emailQueue.add("reminder", { userId: 42 }, { delay: 24 * 60 * 60 * 1000 });   // run in 24 h

const worker = new Worker(
  "email",
  async (job) => {
    if (job.name === "welcome") await sendEmail(job.data.to, job.data.template);
    if (job.name === "reminder") await sendReminder(job.data.userId);
    await job.updateProgress(100);
    return { sent: true };                        // stored as job.returnvalue
  },
  { connection, concurrency: 5, limiter: { max: 100, duration: 60_000 } },   // 100 jobs/min across all workers
);

worker.on("completed", (job) => console.log(`${job.name} ${job.id} done`));
worker.on("failed", (job, err) => console.error(`${job?.name} ${job?.id} failed: ${err.message}`));
worker.on("error", (err) => console.error("worker error", err));   // without a listener errors only reach stderr