Overview
The RedisConnection class manages the connection to Redis for BullMQ. It handles connection lifecycle, version checking, and script loading.
You typically don’t need to use this class directly. BullMQ classes like Queue and Worker handle connections automatically.
Constructor
new RedisConnection(
opts: ConnectionOptions,
extraOptions?: {
shared?: boolean;
blocking?: boolean;
skipVersionCheck?: boolean;
skipWaitingForReady?: boolean;
}
)
opts
ConnectionOptions
required
Redis connection options (ioredis configuration or Redis instance)
Whether this connection is shared
Whether this connection supports blocking operations
Skip Redis version validation
Don’t wait for connection to be ready
Properties
client
client: Promise<RedisClient>
status
status: 'initializing' | 'ready' | 'closing' | 'closed'
capabilities
capabilities: {
canDoubleTimeout: boolean;
canBlockFor1Ms: boolean;
}
redisVersion
The detected Redis server version.
databaseType
databaseType: 'redis' | 'dragonfly' | 'valkey'
Methods
disconnect
Disconnects from Redis.
disconnect(wait?: boolean): Promise<void>
Whether to wait for disconnection to complete
reconnect
Reconnects to Redis.
reconnect(): Promise<void>
close
Closes the connection.
close(force?: boolean): Promise<void>
Force close without waiting
Static Methods
waitUntilReady
Waits for a Redis client to be ready.
static waitUntilReady(client: RedisClient): Promise<void>
Static Properties
minimumVersion
static minimumVersion = '5.0.0'
recommendedMinimumVersion
static recommendedMinimumVersion = '6.2.0'
ConnectionOptions
type ConnectionOptions = RedisOptions | RedisClient;
Using ioredis Options
import { Queue } from 'bullmq';
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
password: 'mypassword',
db: 0,
},
});
Using Existing Redis Instance
import { Queue } from 'bullmq';
import IORedis from 'ioredis';
const connection = new IORedis({
host: 'localhost',
port: 6379,
maxRetriesPerRequest: null,
});
const queue = new Queue('myQueue', { connection });
Redis Cluster
import { Queue } from 'bullmq';
import IORedis from 'ioredis';
const connection = new IORedis.Cluster([
{ host: 'localhost', port: 6379 },
{ host: 'localhost', port: 6380 },
]);
const queue = new Queue('myQueue', { connection });
Events
The RedisConnection class extends EventEmitter and emits the following events:
ready
Emitted when the connection is ready.
connection.on('ready', () => {
console.log('Connection ready');
});
error
Emitted when a connection error occurs.
connection.on('error', (error: Error) => {
console.error('Connection error:', error);
});
close
Emitted when the connection closes.
connection.on('close', () => {
console.log('Connection closed');
});
Version Requirements
BullMQ requires:
- Minimum version: Redis 5.0.0
- Recommended version: Redis 6.2.0 or higher
The connection will check the version automatically unless skipVersionCheck is enabled.
Important Notes
maxRetriesPerRequest
For blocking connections (Workers), BullMQ requires maxRetriesPerRequest: null:
// Correct
const connection = new IORedis({
host: 'localhost',
port: 6379,
maxRetriesPerRequest: null, // Required for Workers
});
// BullMQ will automatically set this for you
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
},
});
Shared Connections
Multiple BullMQ instances can share the same Redis connection:
import IORedis from 'ioredis';
const connection = new IORedis({
host: 'localhost',
port: 6379,
maxRetriesPerRequest: null,
});
// Both instances share the same connection
const queue1 = new Queue('queue1', { connection });
const queue2 = new Queue('queue2', { connection });
