Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

What's New?

v7.0.2

Bulk dispatch now announces publication results for the final partial chunk as well as full chunks. A partial chunk continues to use a provider's pushMany API, including when only one job remains. See Queue Observability.

v7.0.1

Added six observation hooks for publication results and worker attempts: onCBQJobPublished, onCBQJobPublishException, onCBQJobAttemptScheduled, onCBQJobExecutionStarted, onCBQJobExecutionExited, and onCBQJobAttemptFinished. Each attempt has an executionId for correlation across threads and retries. Exceptions from these observers are reported without changing queue outcomes. See Queue Observability.

Use 7.0.2+ when observing bulk dispatch with batchSize > 1; 7.0.1 omits the publication-result hooks for the final partial chunk.

v7.0.0

Breaking Changes

  • Batch result accounting requires a nullable processedJobIds column. Under a row lock, the repository records each job ID once so repeated terminal callbacks do not reduce pendingJobs again or repeat lifecycle dispatch.

  • Persisted job attempts now use a bigint, allowing long-lived retries and manual releases to exceed the old tiny-integer limit.

Apply migrations 2000_01_01_000010_widen_job_attempts.cfc and 2000_01_01_000011_track_processed_batch_jobs.cfc to the tables you use before starting the upgraded application. Custom batch repositories and providers overriding forceFailJob also need to follow the updated contracts. See the v6 to v7 upgrade guide.

Features and Fixes

  • Configure database polling with the per-connection pollIntervalMilliseconds property. It defaults to 5000 and must be a positive integer. See DBProvider.

  • Opt in to chunked database inserts using Dispatcher@cbq.bulkDispatch( batchSize = ... ), from 1 to 100 jobs per chunk. Jobs retain individual queue rows and lifecycles. See Bulk Dispatch.

  • Database callbacks are checked against their execution attempt and reservation state, so a late callback cannot overwrite a reclaimed attempt's queue row.

  • A database worker that lacks a job's WireBox mapping releases its reservation without consuming an attempt or marking the job failed, then continues polling. Route incompatible workers to separate queues.

  • Queue names and serialized payloads are bound as text, avoiding numeric inference for numeric-looking values.

v6.0.2

The DBProvider counts attempts once per execution. Releasing or retrying a database job no longer consumes an extra attempt, so maxAttempts applies to actual executions.

v6.0.1

Fixed PostgreSQL reservation queries so jobs are selected in the intended order before they are locked.

v6.0.0

Breaking Change

Batch accounting now requires a successfulJobs column on the batch table. Apply 2000_01_01_000008_add_successfulJobs_to_cbq_batches_table.cfc before starting the upgraded application, including when using a custom batch table. See the v5 to v6 upgrade guide.

Successful and failed jobs both reduce pendingJobs. The onComplete lifecycle job can therefore run when the final job fails, as well as when it succeeds. Batch names are optional; migration 2000_01_01_000009_make_cbq_batches_name_nullable.cfc makes the name column nullable.

v5.0.8 and v5.0.9

These releases introduced the batch-accounting work finalized in v6, along with DBProvider reservation and retry recovery fixes. v5.0.8 and v5.0.9 already require the successfulJobs column despite its patch version; follow the v6 migration instructions when upgrading from an earlier v5 release.

Other fixes include composing delayed ColdBoxAsyncProvider execution correctly, accepting missing exception information in failed-job logs, and recovering orphaned database reservations whose reservedBy is set but reservedDate is null.

v5.0.7

Update release to use the new push method signature.

v5.0.6

Do not return anything from the shutdown method.

v5.0.5

Make shutdown methods public.

v5.0.4

Add shutdown pass through method to the QueueProvider.

v5.0.3

Fix shutdown on unload logic,

v5.0.2

Fixed a missing reference to config when unloading cbq.

v5.0.1

Added the exception to afterJobException and afterJobFailed lifecycle method arguments.

v5.0.0

Breaking Change

The full AbstractJob instance is now passed in to the push method as job, rather than just the serialized version as payload. All built-in Providers have been updated to handle this change. Custom Providers will need to update to the new method signature.

See the Upgrade Guide for more information.

Other Changes

  • Allow jobs to be fully cancelled manually from inside the job, preventing further retries.

  • Added an afterJobException Provider-level event method to let providers act on any exception, not just the exception that marked the Job as fully failed.

  • A providerContext field is now available on Job instances. This field should only be used in Providers. It can be used to store any value the Provider needs when interacting with Jobs in later lifecycle methods.

  • When processing an unload event, cbq will call a shutdown method on all Connection instances and WorkerPool instances giving Providers a chance to cleanup any necessary code.

  • cbq will now start processing its configuration only after all modules have loaded (afterAspectsLoad).

v4.0.0

Breaking Change

On Batches, the finally and catch methods have been deprecated in order to support Adobe ColdFusion.

finally -> onComplete

catch -> onFailure

If you are running on Lucee or BoxLang, the old methods names will still work, but they may be removed in a future version. We recommend migrating to the new method names.

v3.0.2

  • Add error logging around logging failed jobs.

v3.0.1

  • DBProvider: Fix releasing job timeouts using the wrong value

v3.0.0

  • The failedDate column now uses a Unix timestamp as the column type. This avoids any timezone issues and aligns more closely with the cbq_jobs table used by the DBProvider.

  • Allow worker pools to finish currently running jobs, up to a configurable timeout.

  • Add optional clean-up tasks for completed or failed jobs, failed job logs, and completed or cancelled batches.

  • DBProvider: Improve database locking to avoid duplicate runs of the same job.

  • Fixes unwrapping an optional in a log message.

v2.1.0

Add back ability to work on multiple queues on a per-Provider basis. Currently only the DBProvider supports it.

Add support for before and after lifecycle methods on a Job instance.

Add ability to restrict interceptor execution with a jobPattern annotation. (This is similar to the eventPattern annotation provided by ColdBox.)

v2.0.5

DBProvider: Disable forceRun because it is causing ColdBox Futures to lose mappings.

v2.0.4

Reload module mappings in an attempt to work around ColdBox Async losing them.

v2.0.3

SyncProvider: Add pool to releaseJob call

v2.0.2

Fix moduleSettings missing a queryOptions key for failed jobs

v2.0.1

ColdBoxAsyncProvider now correctly respects Worker Pool conifguration, including queues.

v2.0.0

BREAKING CHANGES

Worker Pools can only define a single queue to work

In order to work with new Queue Providers, the Worker Pools need to be updated to only work a specific queue. This is because many future Queue Providers like RabbitMQ and Amazon SQS only support listening to a single queue in a consumer.

If you previously had multiple queues defined in a Worker Pool, you will need to define multiple Worker Pool instances, one for each of the queues.

Notice that the method has been renamed from onQueues to onQueue.

Additionally, there are no more wildcard queues. Every queue you publish to must have a WorkerPool defined in order for that Job to be worked.

Finally, queue priorities are defined by the number of workers (quantity) you define for the WorkerPool. WorkerPools can no longer share workers across queues.

PreviousHome
NextUpgrade Guide

Last updated