Queue deduplication, heartbeats, and safer job loading

Upgrade notes

@adonisjs/queue now uses @boringnode/queue@0.6.0, which adds job deduplication and worker heartbeats.

See https://github.com/boringnode/queue/releases/tag/v0.6.0

If you use the database driver and already have a queue_jobs table, run the schema helper once before using the new .dedup() API:

import { QueueSchemaService } from '@adonisjs/queue'

const schema = new QueueSchemaService(db.getWriteClient())
await schema.addDedupColumns()

If you use a custom jobs table name, pass it explicitly:

await schema.addDedupColumns('my_queue_jobs')

New queue_jobs tables created by the default migration already include these columns.

Deduplication is supported by the Redis and database drivers. The sync driver still executes every dispatch inline, and deduplication does not apply to batch dispatches or scheduled jobs.

If you maintain a custom queue adapter, it must now implement the new renewJobs(queue, jobIds) method used by worker heartbeats.

Job loading lifecycle

Jobs are no longer imported during the provider boot() phase. The queue manager is still initialized during boot, but job discovery now runs during the application start() phase outside of the console environment.

This avoids importing job files before AdonisJS services such as hash, db, or other booted services have been resolved. It fixes cases where a discovered job imports an application model, and that model captures an unresolved service during boot.

Console commands continue to avoid automatic job discovery. Commands that need jobs, such as queue:work, load them explicitly before starting the worker.

Queue Worker Job Loading Fix

0.6.1 (2026-05-11)

This release updates @boringnode/queue to v0.5.2 and fixes when jobs are loaded during AdonisJS command execution.

See https://github.com/boringnode/queue/releases/tag/v0.5.2

Bug Fixes

• defer automatic job loading in console commands
• explicitly load jobs inside queue:work before starting the worker
• prevent queue:work from loading the same job files twice

Experimental Otel integration

0.6.0 (2026-03-23)

See https://github.com/boringnode/queue/releases/tag/v0.5.1

Bug Fixes

• queue: update job locations to include JavaScript files (f2ba186)
• stub: update migration stub to not import from boringnode/queue (7e34cbd)

Features

• add otel export path (9727658)

Queue Runtime and Lifecycle Fixes

Updating @boringnode/queue to its latest version.

See https://github.com/boringnode/queue/releases/tag/v0.5.0

---

Breaking Changes

QueueManager.getMergedRetryConfig(), QueueManager.getMergedJobOptions(), and QueueManager.getWorkerTimeout() have been removed from the public API.

Effective runtime configuration is now resolved through QueueManager.getConfigResolver(). The merge precedence is unchanged.

Worker.stop() also no longer destroys the underlying adapter instance.

Stopping a worker now only:

• stops pulling new jobs
• waits for in-flight jobs to finish
• removes shutdown handlers

Adapter cleanup is now owned by QueueManager.destroy().

Correct migration stub

0.4.2 (2026-03-06)

Bug Fixes

• stub: correct how we are getting db in migration (dcde1ee)

Support stable AdonisJS 7

This release updates @adonisjs/queue to align with the stable AdonisJS 7 ecosystem.

It is primarily a compatibility and maintenance release.

Release 0.4.0

0.4.0 (2026-02-16)

Features

• add scheduler preload file during configure (52d877b)

Job Retention, Bulk Dispatch & Storage Redesign

⚠️ Breaking Changes - Please read the migration guide carefully before upgrading.

This release updates @adonisjs/queue to use @boringnode/queue v0.3.x which includes a complete storage redesign. See the https://github.com/boringnode/queue/releases/tag/v0.3.0 for details.

Breaking Changes

Storage Migration Required

Both Redis and Database adapters have been redesigned. Existing data is incompatible and requires migration.

For Redis users:

• Jobs now use dedicated hash storage with separate sets for queue states
• Either flush old keys or wait for existing jobs to complete before upgrading

For Database users:

Run a migration to add the new columns:

// database/migrations/xxxx_update_queue_jobs.ts
import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  async up() {
    this.schema.alterTable('queue_jobs', (table) => {
      table.bigint('finished_at').unsigned().nullable()
      table.text('error').nullable()
      table.index(['queue', 'status', 'finished_at'])
    })

    // Update status enum to include new values
    // PostgreSQL: ALTER TYPE ... ADD VALUE
    // MySQL: ALTER TABLE ... MODIFY COLUMN
    // SQLite: Recreate table
  }
}

Note

New projects using node ace queue:migration will automatically get the updated schema.

New Features

Bulk Job Dispatch

Dispatch multiple jobs efficiently in a single batch operation:

await SendEmailJob.dispatchMany([
  { to: 'user1@example.com', subject: 'Newsletter' },
  { to: 'user2@example.com', subject: 'Newsletter' },
])
  .group('newsletter-jan-2025')
  .toQueue('emails')
  .run()

Job Grouping

Organize related jobs together for easier monitoring:

await ExportJob.dispatch(data)
  .group('export-batch-123')
  .run()

Job Retention Control

Configure how long completed/failed jobs are kept:

// config/queue.ts
export default defineConfig({
  removeOnComplete: { age: 3600 }, // Keep for 1 hour
  removeOnFail: { count: 1000 },   // Keep last 1000 failed jobs
})

Release 0.2.2

0.2.2 (2026-01-08)

Bug Fixes

• inject jobFactory to queue work command (90b276d)

Correct Resolve Config Provider

0.2.1 (2026-01-07)

Bug Fixes

• JobOptions wrong import for in stub (b633833)
• resolve config providers in queue:work command (1592098)
• stub: update migration stub to be 1-1 with boringnode/queue (505aad4)