Knowledge base
CodexGuild Knowledge Base

BullMQ v6: pluggable backends, PostgreSQL support, and removal of repeatable jobs and debounce

as of Oct 1, 2026 · applies to bullmq >= 6.0 · canonical · codexguild.com/kb/kb-bullmq-v6-migration-2026 · exported 2026-10-11
Canonical as of Oct 1, 2026

BullMQ v6: pluggable backends, PostgreSQL support, and removal of repeatable jobs and debounce

BullMQ 6 (6.0.0 on 2026-07-30, now 6.3.11) adds Redis/PostgreSQL backends, removes legacy repeatable jobs and debounce, makes ioredis an optional peer, and hides Redis internals. Migrate to Job Schedulers on v5 before upgrading.

BullMQ v6 (2026): pluggable backends, PostgreSQL, repeatable jobs removed

As of: 2026-10

Current versions

  • BullMQ 6.3.11 (2026-10-01) is npm latest. 6.0.0 shipped 2026-07-30.
  • v5 is still patched on the release-v5.x tag (5.81.5, 2026-09-10).
  • v6 requires Node.js >= 14.17.0.

What v6 changed

v6 introduces an IQueueBackend abstraction with Redis (default) and PostgreSQL backends. Breaking changes from the 6.0.0 release notes and migration guide:

  • Legacy repeatable jobs are removed: repeat option on add/addBulk, the Repeat class, getRepeatableJobs(), removeRepeatable(), removeRepeatableByKey(). Use Job Schedulers (upsertJobScheduler, getJobSchedulers, removeJobScheduler). v6 throws if it finds legacy repeatable metadata in Redis.
  • repeat.utc: true -> { tz: 'UTC' }; cron-parser currentDate/nthDayOfWeek options removed.
  • debounce option, Job#debounceId and the debounced event are removed -> deduplication, Job#deduplicationId, deduplicated event. Deduplication is not allowed on parent flow nodes.
  • ioredis is no longer a direct dependency; it is an optional peer. Redis users must npm i ioredis.
  • Redis internals are no longer exposed: Queue#client, Queue#redisVersion, Queue#databaseType, Worker#blockingClient, FlowProducer#client removed; get the raw client via the RedisQueueBackend from getBackend(). Worker#waitUntilReady() resolves to void. The optional 3rd/last constructor argument is now a backend factory, not a Connection.
  • resume() is async and must be awaited.
  • Job#discard() removed -> throw UnrecoverableError.
  • The paused state is gone from JobType/getJobCounts(); jobs in a paused queue count as waiting.
  • FlowProducer nodes without opts.jobId get UUIDs.
  • Telemetry: Meter#createGauge() required; JobState replaces removed attributes; clean() reports only a count.
  • Scripts, createScripts, JobJsonRaw, RedisJobOptions exports removed.

Migration path (do it while still on v5)

// 1. on latest v5: convert each repeatable job
await queue.upsertJobScheduler(
  'paint-daily',
  { pattern: '0 15 3 * * *', tz: 'UTC' },
  { name: 'paint', data: { color: 'blue' }, opts: { attempts: 5 } },
);
// 2. verify with getJobSchedulers(), then removeRepeatableByKey(old.key)
// 3. only then deploy v6 producers AND workers

Redis connection options are unchanged ({ connection: { host, port } } or a shared IORedis instance with maxRetriesPerRequest: null for workers).

PostgreSQL backend

import { Queue, Worker, createPostgresBackend, runMigrations } from 'bullmq';
const opts = { connection: 'postgres://user:pass@localhost:5432/mydb' };
const queue = new Queue('q', opts, createPostgresBackend);
const worker = new Worker('q', async job => {}, opts, createPostgresBackend);
  • Requires PostgreSQL >= 13 and the optional peer pg.
  • Since 6.1.0 (2026-08-12) schema migrations are explicit: call runMigrations(client) once from a deploy step; connections do not migrate automatically. Schema downgrades are unsupported, and older client majors fail with SchemaVersionMismatchError.
  • Typing gotcha: new Queue<Data, Result>(name, opts, createPostgresBackend) fails because remaining type params default to Redis; either omit type args or specify all of them.
  • 6.2.0 added a generic ProgressType parameter on Job/Worker.

What to do now

New projects: bullmq@^6 plus ioredis (or pg). Existing v5 users: upgrade to the latest 5.81.x, migrate repeatable jobs and debounce usage, then move all producers and workers to v6 together.

Sources