Documentation Index
Fetch the complete documentation index at: https://mintlify.com/taskforcesh/bullmq/llms.txt
Use this file to discover all available pages before exploring further.
Overview
ConnectionOptions defines how BullMQ connects to Redis. You can provide either ioredis configuration options or an existing Redis client instance.
Type Definition
type ConnectionOptions = RedisOptions | RedisClient;
Using RedisOptions
Provide ioredis configuration as an object:
import { Queue } from 'bullmq';
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
password: 'mypassword',
db: 0,
},
});
Common RedisOptions Properties
host
host
string
default:"'127.0.0.1'"
Redis server hostname
port
password
username
Redis username (for Redis 6+ ACL)
tls
maxRetriesPerRequest
Maximum retry attempts per request. Must be null for Workers
retryStrategy
Function to determine retry delay
Examples
Basic Connection
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
},
});
With Authentication
const queue = new Queue('myQueue', {
connection: {
host: 'redis.example.com',
port: 6379,
password: 'secure-password',
},
});
With Redis 6 ACL
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
username: 'worker-user',
password: 'worker-password',
},
});
With TLS
const queue = new Queue('myQueue', {
connection: {
host: 'redis.example.com',
port: 6380,
tls: {
rejectUnauthorized: true,
ca: fs.readFileSync('ca.crt'),
},
},
});
With Custom Retry Strategy
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
retryStrategy: (times) => {
// Exponential backoff with max 20 seconds
return Math.min(times * 1000, 20000);
},
},
});
Using Redis URL
const queue = new Queue('myQueue', {
connection: {
url: 'redis://user:password@localhost:6379/0',
},
});
Using Existing Redis Client
You can pass an existing ioredis client instance:
import IORedis from 'ioredis';
import { Queue, Worker } from 'bullmq';
const connection = new IORedis({
host: 'localhost',
port: 6379,
maxRetriesPerRequest: null, // Required for Workers
});
const queue = new Queue('myQueue', { connection });
const worker = new Worker('myQueue', processor, { connection });
Redis Cluster
For Redis Cluster, create an ioredis Cluster instance:
import IORedis from 'ioredis';
const connection = new IORedis.Cluster([
{ host: 'node1.example.com', port: 6379 },
{ host: 'node2.example.com', port: 6379 },
{ host: 'node3.example.com', port: 6379 },
], {
redisOptions: {
password: 'cluster-password',
},
});
const queue = new Queue('myQueue', { connection });
Redis Sentinel
For Redis Sentinel:
const queue = new Queue('myQueue', {
connection: {
sentinels: [
{ host: 'sentinel1.example.com', port: 26379 },
{ host: 'sentinel2.example.com', port: 26379 },
{ host: 'sentinel3.example.com', port: 26379 },
],
name: 'mymaster',
password: 'redis-password',
},
});
Important Notes
maxRetriesPerRequest for Workers
Workers require maxRetriesPerRequest: null because they use blocking operations:
// Correct for Workers
const connection = new IORedis({
host: 'localhost',
port: 6379,
maxRetriesPerRequest: null,
});
const worker = new Worker('myQueue', processor, { connection });
Connection Sharing
Multiple BullMQ instances can share the same connection:
import IORedis from 'ioredis';
const connection = new IORedis({
host: 'localhost',
port: 6379,
maxRetriesPerRequest: null,
});
const queue1 = new Queue('queue1', { connection });
const queue2 = new Queue('queue2', { connection });
const worker1 = new Worker('queue1', processor1, { connection });
const worker2 = new Worker('queue2', processor2, { connection });
Closing Shared Connections
When sharing connections, close the connection manually after closing all instances:
await queue1.close();
await queue2.close();
await worker1.close();
await worker2.close();
// Now close the shared connection
await connection.quit();
Environment Variables
You can use environment variables for connection configuration:
const queue = new Queue('myQueue', {
connection: {
host: process.env.REDIS_HOST || 'localhost',
port: parseInt(process.env.REDIS_PORT || '6379'),
password: process.env.REDIS_PASSWORD,
db: parseInt(process.env.REDIS_DB || '0'),
},
});
