# Redis with BullMQ

```json metadata
{
  "schema_version": 2,
  "title": "Redis with BullMQ",
  "description": "Run Node.js background jobs with BullMQ and Redis.",
  "categories": ["docs","integrate","oss","rs","rc"],
  "group": "library",
  "tableOfContents": {"sections":[{"id":"requirements","title":"Requirements"},{"id":"add-and-process-jobs","title":"Add and process jobs"},{"id":"retry-delay-and-repeat-jobs","title":"Retry, delay, and repeat jobs"},{"id":"what-bullmq-stores-in-redis","title":"What BullMQ stores in Redis"},{"id":"use-node-redis","title":"Use node-redis"},{"id":"more-information","title":"More information"}]}

,
  "codeExamples": []
}
```


[BullMQ](https://docs.bullmq.io/) is a job queue for Node.js (and other languages) that
stores its queues in Redis. A `Queue` adds jobs, a `Worker` processes them, and
`QueueEvents` reports what happened. See the
[job queue use case](https://redis.io/docs/latest/develop/use-cases/job-queue) for when to
choose this pattern.

## Requirements

The examples on this page were run with BullMQ 6.7 and Node.js 23 against Redis 7.2.
BullMQ checks the server version at startup. It requires Redis 5.0 or later and recommends
6.2 or later.

BullMQ 6 doesn't install a Redis client for you. Install it with
[ioredis](https://redis.io/docs/latest/develop/clients/ioredis), or with
[node-redis](https://redis.io/docs/latest/develop/clients/nodejs) as described
[below](#use-node-redis):

```bash
npm install bullmq ioredis
```

You also need a running Redis server. You can run one locally with
[Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis),
use [Docker](https://hub.docker.com/_/redis), or connect to
[Redis Cloud](https://redis.io/cloud/).

## Add and process jobs

Create a `Queue` and add jobs to it. Create a `Worker` with the same queue name and a
function that processes each job. Both take a `connection` that points at Redis:

```js
import { Queue, Worker, QueueEvents } from 'bullmq';

const connection = { host: '<your-redis-host>', port: 6379 };

const queue = new Queue('emails', { connection });

const worker = new Worker('emails', async (job) => {
  return { sent: job.data.to };
}, { connection, concurrency: 5 });

const events = new QueueEvents('emails', { connection });
events.on('completed', ({ jobId, returnvalue }) => {
  console.log(`completed ${jobId}`, returnvalue);
});

await queue.add('welcome', { to: 'a@example.com' });
```

## Retry, delay, and repeat jobs

Pass options when you add a job. This example retries a job up to 3 times with exponential
backoff, delays another by one second, and gives a third a high priority. A job
scheduler adds a job on a repeating schedule:

```js
await queue.add('flaky', { to: 'b@example.com' },
  { attempts: 3, backoff: { type: 'exponential', delay: 200 } });

await queue.add('later', { to: 'c@example.com' }, { delay: 1000 });

await queue.add('urgent', { to: 'd@example.com' }, { priority: 1 });

await queue.upsertJobScheduler('digest', { every: 700 },
  { name: 'digest', data: { to: 'all' } });
```

In a test run, a job that threw an error on its first two attempts completed on the third,
and the `digest` scheduler produced a new job about every 700 milliseconds.

## What BullMQ stores in Redis

BullMQ stores everything under the prefix `bull:<queue-name>:`:

| Key | Type | Contents |
|-----|------|----------|
| `bull:emails:<job-id>` | hash | The job: `name`, `data`, `opts`, `timestamp`, and `returnvalue` and `finishedOn` once it finishes. |
| `bull:emails:completed` | sorted set | The IDs of completed jobs. |
| `bull:emails:delayed` | sorted set | The IDs of delayed jobs, scored by the time they become ready. |
| `bull:emails:id` | string | The counter that assigns job IDs. |
| `bull:emails:repeat:<scheduler-id>` | | The state for each job scheduler. |

Waiting jobs are stored in a list, `bull:emails:wait`, which exists only while it holds
jobs. Completed jobs stay in Redis until you remove them, so set `removeOnComplete` and
`removeOnFail` on your jobs or workers to stop them accumulating.

## Use node-redis

BullMQ uses ioredis by default. BullMQ 6 can use the
[node-redis](https://redis.io/docs/latest/develop/clients/nodejs) client instead, through a factory
that you set once, before you create any queues or workers. Install node-redis 5 or later
(`npm install bullmq redis`) and register the factory:

```js
import { RedisConnection, createNodeRedisClient } from 'bullmq';
import { createClient } from 'redis';

RedisConnection.clientFactory = (opts) => {
  const raw = createClient({ url: `redis://${opts.host ?? '127.0.0.1'}:${opts.port ?? 6379}` });
  return createNodeRedisClient(raw);
};
```

A queue and worker created after this call completed a job in a test run. The factory is
a static setting, so it applies to every BullMQ connection in the process.

## More information

- [BullMQ documentation](https://docs.bullmq.io/)
- [BullMQ on GitHub](https://github.com/taskforcesh/bullmq)

