Skip to main content
BullMQ’s team regularly releases new versions packed with bug fixes, new features, or occasionally, breaking changes. As a user operating in a production environment, you might find upgrading to these new versions while maintaining service continuity challenging. This guide offers tips and advice to ease your transition between versions and from other queue libraries.

​
Migration Paths

Bull to BullMQ

Migrate from the legacy Bull package to BullMQ

Newer BullMQ Versions

Upgrade between BullMQ versions safely

​
Understanding Migration Types

Different types of upgrades require different strategies:
Version Pattern: 3.14.4 → 3.14.7 (micro version change)
  • Risk Level: Low
  • Strategy: Simple update, no code changes needed
  • Downtime: None required
npm install bullmq@latest
While it’s not critical that all instances run the same version, we recommend it for consistency.

​
General Migration Advice

Before Any Upgrade:
  • Always consult the Changelog
  • Avoid large version jumps - upgrade incrementally
  • Test in a staging environment first
1

Start with bugfix releases

Apply all bugfix releases first (e.g., 1.3.7 → 1.3.12)
2

Proceed to new features

Move to the latest minor version (e.g., 1.3.12 → 1.10.5)
3

Finally, major releases

Only then upgrade major versions (e.g., 1.10.5 → 2.0.0)

​
Example Migration Timeline

If you’re on version 1.3.7 and want to reach 4.2.6: 
1.3.7 → 1.3.12 (bugfixes)
  ↓
1.12.0 (new features)
  ↓
2.0.0 (breaking changes)
  ↓
2.14.3 (bugfixes + features)
  ↓
3.0.0 (breaking changes)
  ↓
3.20.5 (bugfixes + features)
  ↓
4.2.6 (breaking changes + features)

​
Migration Strategies

For challenging upgrades, consider these strategies:
Suitable when your business can tolerate a brief pause:
1

Pause all queues

await queue.pause();
2

Wait for active jobs to complete

const activeCount = await queue.getActiveCount();
while (activeCount > 0) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  activeCount = await queue.getActiveCount();
}
3

Upgrade all instances

Deploy new version to all workers and queue instances
4

Unpause queues

await queue.resume();
This strategy is less useful if breaking changes affect Queue instances. Always consult the changelog.
Run old and new versions side-by-side:
  1. Deploy new version alongside old version
  2. Gradually shift traffic to new version
  3. Monitor for issues
  4. Once stable, retire old version
This works best when:
  • You have sufficient infrastructure
  • Changes are additive (not destructive)
  • You can route jobs between versions
The safest but most drastic solution:
1

Create new queues with different names

// Old
const oldQueue = new Queue('myQueue');

// New
const newQueue = new Queue('myQueueV2');
Or use a different prefix:
const newQueue = new Queue('myQueue', {
  prefix: 'bull-v2',
});
2

Run both versions in parallel

  • Old version processes old queues
  • New version processes new queues
  • Direct new jobs to new queues
3

Wait for old queues to drain

Monitor old queues until all jobs are processed
4

Retire old version

Once old queues are empty, shut down old version

​
Testing Migrations

1

Test in staging environment

Always test migrations in a non-production environment first
2

Create test jobs

// Add test jobs to verify functionality
await queue.add('test', { testId: 1 });
await queue.add('test', { testId: 2 });
3

Verify job processing

Ensure jobs are processed correctly with the new version
4

Monitor for errors

Watch logs and error rates during and after migration

​
Monitoring During Migration

Key metrics to watch:

Job Completion Rate

Ensure jobs continue to complete at normal rates

Error Rate

Watch for spikes in errors during migration

Queue Length

Monitor waiting and active job counts

Stalled Jobs

Check for unusual numbers of stalled jobs

​
Need Help?

If you encounter issues during migration:

Bull to BullMQ

Detailed guide for migrating from Bull

Newer Versions

Strategies for upgrading BullMQ versions

Going to Production

Production deployment best practices

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us