11.0.0

⚠️ Please review items listed as MAJOR if upgrading from v10 ⚠️

• MAJOR: Automatic migration from v10 or lower is not supported due to significant job partitioning changes. As with the advice in the v10 release notes, the safest option is to manually move jobs via the API or SQL via INSERT ... SELECT. I always prefer automatic migrations whenever they are easy to run in both directions without data loss, but unfortunately v11 did not pass this test.

• MAJOR: Queues are still using declarative partitioning as before, but they will not automatically create a dedicated table as in v10. This feature is still supported via a new property, partition: boolean, added to createQueue(), and should be reserved for high-volume queues. In some rare use cases, having thousands of queues resulting in thousands of tables combined with some connection poolers produced OOMs related to how query plan caching works internally in Postgres. Thankfully, pg-boss never had any issues opened due to this, but load tests were used to confirm this behavior. Dedicated tables are great for isolation in some cases, but it should be the exception and not the rule, so this will likely remain an opt-in configuration.

• MAJOR: Archive tables have been removed. Previously, it was complicated to know when jobs existed in the archive vs. the job table, so now completed jobs will remain in the job table until they are removed.

  • A new option, deleteAfterSeconds, has been added to createQueue() and send(). The default is 7 days. Please review this for large volume queues, since this setting might need to be adjusted to a shorter duration. Remember that this setting should be at least as much as your largest desired debouncing/throttling time intervals.
  • archive() removed
  • getJobById()'s includeArchive option removed
  • archiveCompletedAfterSeconds option removed
  • archiveFailedAfterSeconds option removed

• MAJOR: Extra time-based configuration settings were removed for simplification.

  Setting	Location	Replacement
  ❌ singletonMinutes	Job	singletonSeconds
  ❌ singletonHours	Job	singletonSeconds
  ❌ retentionMinutes	Queue, Job	retentionSeconds
  ❌ retentionHours	Queue, Job	retentionSeconds
  ❌ retentionDays	Queue, Job	retentionSeconds
  ❌ deleteAfterSeconds	Constructor	Queue, Job: deleteAfterSeconds
  ❌ deleteAfterMinutes	Constructor	Queue, Job: deleteAfterSeconds
  ❌ deleteAfterHours	Constructor	Queue, Job: deleteAfterSeconds
  ❌ deleteAfterDays	Constructor	Queue, Job: deleteAfterSeconds
  ❌ maintenanceIntervalMinutes	Constructor	maintenanceIntervalSeconds * see following MAJOR
  ❌ clockMonitorIntervalMinutes	Constructor	clockMonitorIntervalSeconds

• MAJOR: A subtle difference exists regarding what the terms "supervise" and "maintain" mean, so breaking changes have been made in the API to hopefully clear this up.

  • Supervise: Monitor queues to handle expiration of active jobs, calculate queue stats and potentially issue warnings. Includes maintenance as well.
  • Maintain: Removing completed jobs from the database according to the configured deleteAfterSeconds value, as well as removing queued jobs whose retention policy has expired.
  • A new property superviseIntervalSeconds was added to control how often queues are monitored with a default of 60 seconds.
  • Given the above, the maintenanceIntervalSeconds still exists, but its meaning has been changed. It now defaults to 1 day so maintenance will not be run continuously while monitoring happens.

• MAJOR: insert(PgBoss.JobInsert[]) now requires a queue name as the 1st argument: insert(name: string, PgBoss.JobInsert[]).

• MAJOR: The expireIn: PostgresInterval property for jobs in insert() was renamed to expireInSeconds: number

• MAJOR: event monitor-states has been removed, along with its configuration properties, monitorStateIntervalSeconds and monitorStateIntervalMinutes. All queue monitoring and metrics is now stored in the queue table. You would normally pull this via getQueues(). Examples of new properties are:

  • deferredCount
  • queuedCount
  • activeCount
  • totalCount

  Similarly, getQueueSize(name) has been removed. If you want to bypass the queue stats cache and absolutely need to get immediate stats on a queue, a new function was added just for this purpose, getQueueStats(name).

• MAJOR: Event maintenance has been removed.

• MAJOR: Several queue maintenance functions have been dropped or renamed in favor of a more intuitive API.

  Function	Replacement
  ❌ expire()	supervise()
  ❌ purge()	No replacement. See deleteQueuedJobs(name)
  ❌ purgeQueue(name)	deleteQueuedJobs(name)
  ❌ clearStorage()	No replacement. See deleteAllJobs(name)
  ❌ maintain(name)	deleteStoredJobs(name), to clear stored jobs
  ❌ maintain()	supervise(), for all operations
  ❌ maintain(name)	supervise(name), for all operations

• MAJOR: Node 22 is now the minimum required version

• MINOR: A new event named warning has been added, which adds the ability to notify you when a queue backlog grows too large, or when a query seems to be taking too long to finish. Both of these use cases are good indications that a queue or queues should be tuned and adjusted. The following configuration properties were added to tune these.

  Setting	Location	Default
  warningSlowQuerySeconds: number	Constructor	30
  warningQueueSize: number	Constructor	10_000
  warningQueueSize: number	Queue	0: Inherits value in the constructor above

• MINOR: Queues now support multiple schedules. Previously, you could only set one cron expression, but a new option was added, key, that supports a schedule per unique key. Other convenience overloads were added the unschedule() and getSchedules() APIs to make keys easier to use. This is categorized as minor since it's a backwards compatible change to the current API.

  unschedule(name: string, key?: string): Promise<void>;
  getSchedules(name?: string, key?: string): Promise<PgBoss.Schedule[]>;

• MINOR: A new property, retryDelayMax was added to limit the growth of exponential backoffs during jobs retries. Contributed by @danilofuchs (#531) ❤️

What's Changed

• feat: maxRetryDelay option to limit retryBackoff by @danilofuchs in #531
• V11: retry delay max by @timgit in #567
• v11 by @timgit in #495

Full Changelog: 10.3.3...11.0.0