BullMQ v5 Migration Notes

BullMQ v5 Migration Notes

BullMQ v5 is a major release, and therefore it implies some breaking changes. Fortunately, the impact of these changes is small, so upgrading from version 4 should be quite easy. However, there are some important changes to be aware of, so please read the following notes to avoid any issues.

Improved Queue markers

In BullMQ v5, we have introduced a new mechanism for notifying workers that there are jobs waiting in the queue. This mechanism requires a change in the underlying Redis™ data structure. However, as long as all workers are upgraded to the new version, the migration should be seamless.

Please refer to this article where we explain in detail about the new queue markers.

Better logic for handling "attemptsMade"

In v5, we are improving the way a job's attemptsMade property is increased. Previously, this property would be increased every time a job started. This approach has worked well in the past, but now, as we allow processors to break out in the middle of processing (for example, to implement features like manual rate-limiting), the attemptsMade property will be increased although the job did not finish. This creates issues if the same job fails and should be retried with some backoff function, as the backoff will rely on attemptsMade to calculate the time to wait before the next retry, for exempel as in this issue.

We have thus introduced a new job property called attemptsStarted, which will be incremented each time a job starts, and changed the logic behind attempsMade so that it is only incremented when a job has completed or failed. This will reflect much more accurately what actually happened with the job.

Connection is now a mandatory option.

In v4, a warning was shown if a connection object was not passed to any of the constructors in Queue, Worker and QueueEvents. From v5, this warning will now produce an error. Please ensure you are passing the connection whenever you instantiate any of the aforementioned classes.

Using integers as job ids will throw an error.

Another change that may affect you is that job IDs can no longer be integers; otherwise, an exception will be thrown. This restriction has been implemented because, by default, job IDs are generated using an auto-incremental ID. This could collide with a custom ID and lead to inconsistencies in the queue.

That's all folks

So that would be all, no more breaking changes. It is also highly recommended to read this general migration guide whenever you are upgrading.

If you have any issues you are welcome to discuss it in github or slack

Happy Christmas!