1.1.0

What's New

Expiration callbacks

While job expiration has always been a thing, reacting to them was not as easy. boss.onExpire(jobName, callback) was added to this release to add a listener explicitly for jobs that have expired.

Failure status

• failed was added as a job status.
• pg-boss now emits 'failed' on unhandled subcriber errors instead of 'error', which is far safer considering how node reacts when an EventEmitter emits 'error' when no one is listening. Other unexpected errors during operations will still emit 'error', however.
• done() in suscribe() callbacks now support passing an error (the popular node convention) to automatically mark the job as failed as well as emitting failed. For exampe, if you are processing a job and you want to explicitly mark it as failed, you can just call done(error) at any time.
• Finally, boss.fail(jobId) was also added for external failure reporting for the fetch() and complete() crew.

Thanks to @jordansexton for the suggestion on this one. The world is now a better place. 👍

Unsubscribing

boss.unsubscribe(jobName) was added to allow unsubscribing a previous subscribe(). I don't expect this to be very popular, but it does make the API a bit more flexible and aligns subscriptions with the pattern already in place with other methods. For example, stop() reverses start() and disconnect() reverses connect().

1.0.0

🎉 1.0.0! 🎉

pg-boss turns 1 this week, and after using it in production for the last year it felt fitting to use the latest round of enhancements, fixes and optimizations as an opportunity to bump the version up to 1.0.0 and finally embrace true semver.

What does this break?

A year ago node 0.10 and 0.12 were still very well supported, but i decided to go ahead and drop support for them with 1.0.0 as they are no longer supported node releases. I know with 100% confidence that I broke 0.10 support with this release because of the way 0.10 handled event emitters. While pg-boss should technically still work on 0.12, I no longer run any automated tests on it.

Even though this is major version change, it's not something that will make your current 0.x code break as only additions were made to the API. However, given there were actually database schema changes in 1.0, a migration script needs to be run against any 0.x instances. If you are one of these awesome early pioneers, don't worry too much about the migration because this will be automatic after you upgrade and call start().

As always, if you don't want this to occur automatically, or if your user account doesn't have the required permissions, run getMigrationsPlans() and it will produce the SQL scripts required for migration based on your current version. I added a scripts folder to the repo as an example of how one might go about exporting said SQL if needed.

On 0.x I used minor releases for semver, but now that I'm on 1.x, I hope this removes all doubt regarding versioning in the future as I fully plan on using semver.

What's new?

• Singleon jobs - "I only want 1 job of this type to be running at a time"

  A new publish option called singletonKey was added in order to make sure only 1 job of a certain type is active, queued or in a retry state. Thanks to @jede for the suggestion and feedback on this.

• Throttling "next slot" - "I like throttling, but if my publish request is throttled, please at least queue it up for the next throttling interval"

  A new publish option called singletonNextSlot was added in order to make sure a job is processed eventually, even if it was throttled down (not accepted).

  This is actually something I had way back in 0.3.x, but removed it because it wasn't explicit in the API and made things a little unpredictable.

• Per-subscription new job check interval - "I like the default polling of every second, but only check for this job every 10 seconds".

  The same newJobCheckInterval and newJobCheckIntervalSeconds are now available on subscribe(). They behave the same as the global default used in the constructor and control how often each job type is fetched on a subscription by subscription basis if needed.

  This may not seem all too exciting, but if you use it in combination with teamSize, you can start to realize how this could be helpful in regards to fine tuning your job processing.

• Connection pooling - "I need to ensure that pg-boss will not use more than this number of connections against my database."

  A new option poolSize has been added to the constructor that enforces the maximum number of connections that can be used against the specified database. Thanks to @phips28 for pointing this out.

  Technically connection pooling was configured behind the scenes in 0.x, but since a pool wasn't explicitly set up during pg-boss initialization, it wasn't a guarantee on a maximum number of connections that could be opened against the database.

What's fixed?

• 0.x had a data management bug which caused expired jobs to not be archived and remain in the job table. After this was fixed I also added a fix to the migration script so if you had any old expired jobs they should be automatically archived.

• Error handling in subscriber functions! Previously I've encouraged folks to handle their own errors with try catch and be as defensive as possible in callback functions passed to subscribe(). However, it was too easy to miss that at times and if an error occurred that wasn't caught, it had the pretty lousy side effect of halting all job processing. 1.0.0 now wraps all subscriber functions in try catch blocks and emits the 'error' event if one is encountered.

  Also, please remember that pg-boss is an instance of node's EventEmitter. If an EventEmitter emits 'error' and you haven't written a handler for it, it's kind of a big deal. I updated the primary readme to add this handler because it really should just always be there.

0.5.0

fetch() and complete() were added in 0.5.0 in order to provide a way to request and process jobs externally in contrast to the typical managed polling style in subscribe(). These methods were originally internally facing, but having them publically facing would allow you to build other entry points into the job system such as a web API.

0.2.0

Breaking changes for 0.2.0

Removed ready event during start() and cancel() in favor of a promise API. The readme was updated with the latest API.