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
})