Migration Overview

Guide to migrating to BullMQ from Bull and upgrading between BullMQ versions

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:

Bugfix Releases

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.

New Features

Version Pattern: 3.14.7 → 3.20.5 (minor version change)

• Risk Level: Low to Medium
• Strategy: Update all instances first, then deploy code using new features
• Downtime: None required

1. Update all instances to new version

   npm install bullmq@3.20.5
   
2. Verify all instances are updated

   Check that all workers and queue instances are running the new version

3. Deploy code using new features

   Only after all instances are updated, deploy code that depends on new features

Breaking Changes

Version Pattern: 3.x.x → 4.0.0 (major version change)

• Risk Level: Medium to High
• Strategy: Depends on change type (see below)
• Downtime: May be required

Breaking changes fall into two categories:

API Breaking Changes

• Changed method parameters
• Removed methods
• Different operational methods
• Usually straightforward to fix with tests

Data Structure Breaking Changes

• More challenging
• Can be additive or destructive
• May require special migration strategies

General Migration Advice

Before Any Upgrade:

• Always consult the Changelog
• Avoid large version jumps - upgrade incrementally
• Test in a staging environment first

Recommended Upgrade Path

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:

Pause/Upgrade/Unpause

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.

Blue-Green Deployment

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

Use New Queues

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:

• Check the Troubleshooting guide
• Review the Changelog
• Ask in GitHub Discussions
• Report bugs in GitHub Issues

Related Resources

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