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'),
},
});
