Queue.pause()
Pauses the queue, preventing it from processing new jobs. Current jobs being processed will continue until finalized.
Signature
pause(isLocal?: boolean, doNotWaitActive?: boolean): Promise
Parameters
If true, only this worker instance is paused (local pause). If false, all workers in all queue instances are paused (global pause).
If true, pause() will not wait for active jobs to finish before resolving. If false, it will wait for active jobs to complete.
Returns
A promise that resolves when the queue is paused.
Examples
Global Pause
// Pause all workers across all queue instances
await queue.pause();
console.log('Queue is paused globally');
Local Pause
// Pause only this worker instance
await queue.pause(true);
console.log('This worker is paused');
// Pause immediately without waiting for active jobs
await queue.pause(false, true);
console.log('Queue paused (active jobs still running)');
Graceful Shutdown
// Stop accepting new jobs before shutting down
async function gracefulShutdown() {
console.log('Pausing queue...');
await queue.pause(true); // Wait for current jobs
console.log('Closing queue...');
await queue.close();
console.log('Shutdown complete');
process.exit(0);
}
process.on('SIGTERM', gracefulShutdown);
process.on('SIGINT', gracefulShutdown);
Notes
- Pausing an already paused queue does nothing
- Use local pause to stop a worker from taking new jobs prior to shutting down
- Global pause affects all workers processing the same queue
- Active jobs continue processing unless
doNotWaitActive is true
Queue.resume()
Resumes a paused queue, allowing it to process jobs again.
Signature
resume(isLocal?: boolean): Promise
Parameters
If true, only this worker instance is resumed (local resume). If false, all workers are resumed (global resume).
Returns
A promise that resolves when the queue is resumed.
Examples
Global Resume
// Resume all workers
await queue.resume();
console.log('Queue is resumed globally');
Local Resume
// Resume only this worker
await queue.resume(true);
console.log('This worker is resumed');
Pause and Resume on Schedule
// Pause processing during maintenance window
const maintenanceStart = async () => {
console.log('Starting maintenance - pausing queue');
await queue.pause();
};
const maintenanceEnd = async () => {
console.log('Maintenance complete - resuming queue');
await queue.resume();
};
// Schedule maintenance
schedule.scheduleJob('0 2 * * *', maintenanceStart); // 2 AM
schedule.scheduleJob('0 3 * * *', maintenanceEnd); // 3 AM
Throttling Pattern
let processing = false;
queue.on('error', async (error) => {
if (error.message.includes('RATE_LIMIT') && !processing) {
processing = true;
console.log('Rate limited - pausing for 60 seconds');
await queue.pause();
setTimeout(async () => {
await queue.resume();
processing = false;
console.log('Resumed after rate limit');
}, 60000);
}
});
Notes
- Resuming an already active queue does nothing
- Global resume will NOT resume workers that were paused locally
- Workers paused locally must call
resume(true) directly
- After resume, the queue will immediately start processing waiting jobs
Queue.isPaused()
Checks if the queue is currently paused.
Signature
isPaused(isLocal?: boolean): Promise<boolean>
Parameters
If true, checks if this particular worker instance is paused. If false, checks if the queue is globally paused.
Returns
A promise that resolves to true if the queue is paused, false otherwise.
Examples
Check Global Pause Status
const isPaused = await queue.isPaused();
console.log(`Queue is ${isPaused ? 'paused' : 'active'}`);
Check Local Pause Status
const isLocallyPaused = await queue.isPaused(true);
console.log(`This worker is ${isLocallyPaused ? 'paused' : 'active'}`);
Conditional Job Addition
async function addJobIfActive(jobData) {
const paused = await queue.isPaused();
if (paused) {
console.log('Queue is paused, job will be queued');
}
await queue.add(jobData);
}
Health Check Endpoint
app.get('/queue/health', async (req, res) => {
const paused = await queue.isPaused();
const jobCounts = await queue.getJobCounts();
res.json({
status: paused ? 'paused' : 'active',
paused,
counts: jobCounts
});
});
Queue.whenCurrentJobsFinished()
Waits for all jobs currently being processed by this worker to finish.
Signature
whenCurrentJobsFinished(): Promise<void>
Returns
A promise that resolves when all currently active jobs in this worker have finished.
Examples
Wait for Jobs Before Shutdown
async function shutdown() {
console.log('Waiting for current jobs to finish...');
await queue.whenCurrentJobsFinished();
console.log('All jobs finished, closing queue');
await queue.close();
}
Coordinated Worker Restart
async function restartWorker() {
// Pause to stop accepting new jobs
await queue.pause(true);
// Wait for current jobs to complete
await queue.whenCurrentJobsFinished();
// Perform maintenance or updates
await performMaintenance();
// Resume processing
await queue.resume(true);
}
Graceful Pause
// Pause is equivalent to this when doNotWaitActive is false
async function gracefulPause() {
await queue.pause(false, true); // Pause immediately
await queue.whenCurrentJobsFinished(); // Then wait
console.log('Graceful pause complete');
}
// Same as:
await queue.pause(); // waits by default
Notes
- Only waits for jobs being processed by THIS worker instance
- Does not wait for jobs in other workers
- Useful for graceful shutdowns and worker restarts
pause() internally uses this when doNotWaitActive is false
Common Patterns
Deployment with Zero Downtime
const queue = new Queue('production-queue');
process.on('SIGTERM', async () => {
console.log('SIGTERM received, starting graceful shutdown');
// Stop accepting new jobs
await queue.pause(true);
// Wait for active jobs (with timeout)
const timeout = setTimeout(() => {
console.log('Timeout reached, forcing shutdown');
process.exit(1);
}, 30000); // 30 second timeout
await queue.whenCurrentJobsFinished();
clearTimeout(timeout);
await queue.close();
console.log('Graceful shutdown complete');
process.exit(0);
});
Maintenance Mode
let maintenanceMode = false;
async function enableMaintenance() {
maintenanceMode = true;
await queue.pause();
console.log('Maintenance mode enabled');
}
async function disableMaintenance() {
await queue.resume();
maintenanceMode = false;
console.log('Maintenance mode disabled');
}
// API endpoints
app.post('/admin/maintenance/start', async (req, res) => {
await enableMaintenance();
res.json({ status: 'maintenance enabled' });
});
app.post('/admin/maintenance/end', async (req, res) => {
await disableMaintenance();
res.json({ status: 'maintenance disabled' });
});