Skip to main content
Bull internals require atomic operations that span different keys. This behavior breaks Redis’s rules for cluster configurations. However, it is still possible to use a cluster environment by using the proper Bull prefix option as a cluster hash tag.

​
Hash Tags

Hash tags are used to guarantee that certain keys are placed in the same hash slot. A hash tag is defined with brackets. A key that has a substring inside brackets will use that substring to determine in which hash slot the key will be placed.
Read more about hash tags in the Redis Cluster Tutorial.

​
Solution

To make Bull compatible with Redis Cluster, use a queue prefix inside brackets. 
const queue = new Queue('cluster', {
  prefix: '{myprefix}'
});

​
Multiple Queues

If you use several queues in the same cluster, you should use different prefixes so that the queues are evenly placed in the cluster nodes. 
const emailQueue = new Queue('emails', {
  prefix: '{emails}'
});

​
How It Works

1

Define Hash Tag

Wrap your prefix in curly braces: {myprefix}
2

Key Hashing

Redis uses only the substring within brackets to determine the hash slot
3

Same Slot Guarantee

All keys with the same hash tag are guaranteed to be in the same slot
4

Atomic Operations

Bull can now perform atomic operations across keys in the same slot

​
Complete Example

const Redis = require('ioredis');
const Queue = require('bull');

const cluster = new Redis.Cluster([
  {
    host: 'localhost',
    port: 7000
  },
  {
    host: 'localhost',
    port: 7001
  },
  {
    host: 'localhost',
    port: 7002
  }
]);

const queue = new Queue('my-queue', {
  prefix: '{bull}',
  createClient: function(type) {
    switch(type) {
      case 'client':
        return cluster;
      case 'subscriber':
        return cluster.duplicate();
      case 'bclient':
        return cluster.duplicate();
      default:
        throw new Error('Unexpected connection type: ' + type);
    }
  }
});
Critical: Without hash tags, Bull will not work correctly with Redis Cluster because atomic operations will fail when they span keys in different slots.

​
Key Distribution

Single Prefix

All queues with {myprefix} will be on the same nodeGood for: Single queue or queues that need to share atomic operations

Multiple Prefixes

Each unique prefix distributes to different nodesGood for: Load balancing across cluster nodes

Build docs developers (and LLMs) love

Get started for freeTalk to us