@pauldeng/node-red-contrib-bullmq 1.0.2 → 2.0.0

package/docs/ARCHITECTURE.md

@@ -6,47 +6,93 @@ The package remains a single Node-RED module entry point, but BullMQ behavior is
 
 `bull-queue.js` registers:
 
-- `bull-queue-server`
-- `bull cmd`
-- `bull run`
-- `bull job`
-- `bull events`
-- `bull flow`
+- `bullmq-queue-server`
+- `bullmq cmd`
+- `bullmq run`
+- `bullmq job`
+- `bullmq events`
+- `bullmq flow`
 
 The runtime does Node-RED lifecycle work only: creating nodes, wiring input handlers, setting status, and closing resources.
 
+## Backends
+
+BullMQ v6 reaches its datastore through `IQueueBackend`, and this package selects one per config node with `backend`. Absent or blank means Redis, matching a flow saved before the field existed.
+
+The seam is a factory argument on the BullMQ constructors, and its position differs per class: `Queue(name, opts, factory)` and `QueueEvents(name, opts, factory)` take it third, `Worker(name, processor, opts, factory)` fourth, and `FlowProducer(opts, factory)` **second**. Redis is BullMQ's default, so the Redis path passes no factory at all; the PostgreSQL path passes `createPostgresBackend`. `setDefaultBackendFactory` is deliberately unused: a process-wide default would make two config nodes with different backends impossible.
+
+What each backend owns is the asymmetry the rest of this document keeps returning to. On Redis this package creates the ioredis connections and hands them over, so it holds a raw client per owner. On PostgreSQL BullMQ owns everything — a `pg` pool per backend plus a dedicated `LISTEN` client for Worker and QueueEvents — so this package creates no connection, tracks the owner with no connection value, and has no raw handle to reach for. `pg` is loaded lazily by BullMQ while constructing the queue, which is why a missing install surfaces synchronously out of the constructor rather than through `waitUntilReady()`.
+
+Three operations in BullMQ 6.3.1's PostgreSQL adapter throw `not implemented`: `trimEvents`, `removeDeprecatedPriorityKey`, and `paginate` outside a flow's `:dependencies`/`:processed` keys. None is on a path these nodes use. `publishEvent` accepts but ignores `maxEvents`, so PostgreSQL event rows are never trimmed — recorded in [CONNECTIONS.md](CONNECTIONS.md#what-postgresql-does-not-have) as a standing limitation rather than worked around here.
+
 ## Connections
 
-`bull-queue-server` owns queue name and Redis deployment config. It creates role-specific ioredis connections:
+`bullmq-queue-server` owns queue name and connection config. On Redis it creates role-specific ioredis connections:
 
-- producer connections fail quickly with bounded retries;
-- worker and event connections use `maxRetriesPerRequest: null`;
+- producer connections fail fast through `skipWaitingForReady: true` on the BullMQ owner plus `maxRetriesPerRequest: 1` on the socket. Without the first, BullMQ awaits a connection-ready promise that never settles while Redis is unreachable, so a `bullmq cmd` command hangs instead of erroring and the node never calls `done()`. The offline queue is deliberately left enabled so messages emitted during the brief connection window after a deploy are buffered;
+- worker and event connections use `maxRetriesPerRequest: null` and keep the offline queue, because a consumer should wait for the connection to come back rather than fail;
+- every role reconnects with exponential backoff between 1s and 20s, including Cluster and Sentinel discovery retries;
 - QueueEvents uses a dedicated connection;
 - Cluster and MemoryDB use `{bull}` by default as the BullMQ prefix.
 
-Connection and resource errors are reported on the consuming runtime node's status (`bull run`, `bull events`, `bull flow`). The shared producer connection and queue used by `bull cmd` report on the config node.
+None of the above applies to PostgreSQL: readiness, retry, and offline-queue behavior are ioredis concepts, `skipWaitingForReady` is never read on that path, and there is no prefix. A PostgreSQL config node instead carries the pool size, schema, and migration switch described in [CONNECTIONS.md](CONNECTIONS.md#postgresql).
+
+Each BullMQ owner (`Queue`, `Worker`, `QueueEvents`, or `FlowProducer`) is tracked with its owned ioredis connection, or with no connection at all on PostgreSQL. A runtime node releases its pair on redeploy; config-node shutdown closes independent pairs concurrently. See Shutdown below for how each owner/connection pair actually closes.
+
+Connection and resource errors are reported on the consuming runtime node's status (`bullmq run`, `bullmq events`, `bullmq flow`). The config node owns the shared queue and its producer connection. Each `bullmq cmd` mirrors that shared queue's backend (`Queue.getBackend()`, BullMQ's `IQueueBackend`) on its visible status instead of reading the producer connection directly, while Queue errors report on the config node.
+
+Secrets are read only from Node-RED credentials.
+
+Queue retention defaults are attached directly to `Queue`. For a single tree, `bullmq flow` builds BullMQ `queuesOptions` for every queue name so the same defaults also reach `FlowProducer`. For a bulk array, whose BullMQ API accepts no options argument, it stamps the defaults onto each job's `opts`. Both paths preserve job-level overrides.
+
+## Shutdown
 
-Secrets are read from Node-RED credentials first, with legacy plain fields accepted only for backward compatibility.
+Closing an owner/connection pair (`bull-queue.js`) uses a budget chosen from the resource ownership already recorded in the config node's `resources` map:
+
+- A Redis owner with a ready companion ioredis connection gets `GRACEFUL_CLOSE_MS` (10 seconds). `Worker.close()` waits for in-flight jobs, and cutting that off abandons a running job to the stalled checker, which re-runs it and can eventually fail it for exceeding `maxStalledCount`.
+- A Redis owner whose companion connection is not ready gets `CLOSE_GRACE_MS` (1 second), followed by the Redis force-disconnect fallback.
+- A PostgreSQL owner has no companion connection because BullMQ owns its pool. It gets `POSTGRES_CLOSE_MS` (11 seconds), derived as `POSTGRES_CONNECTION_TIMEOUT_MS` (the 10-second `connectionTimeoutMillis` this package fixes in `lib/connections.js`) plus one second of scheduling margin, so raising that timeout cannot leave the budget short. PostgreSQL exposes no raw client that this package can safely force closed, so Node-RED must await pg's own timeout before reporting close complete.
+
+Pairs close concurrently, so these budgets bound one resource rather than adding across all resources. They also avoid using the config node's shared `backendStatus`: that status belongs to the shared `Queue`, so a config node backing only a `bullmq run` node may never advance it.
+
+Within that budget:
+
+1. The BullMQ owner's own graceful close (`Queue.close()` / `Worker.close()` / `QueueEvents.close()` / `FlowProducer.close()`). This alone succeeds whenever the datastore is reachable.
+2. If graceful close times out, force-disconnect and stop Worker lock-renewal/stalled-check timers (`forceDisconnect`).
+
+Step 2 differs by backend:
+
+- **Redis**: force-disconnect the backend's raw ioredis clients (`connection._client` / `blockingConnection._client`), behind an `IQueueBackend` capability check (`typeof resource.getBackend === "function"`). This escalation is deliberately tied to the exact BullMQ 6.3.1 pin: its public `disconnect()` awaits the same never-ready connection promise as `close()`, so calling it would spend a second grace period without improving shutdown. Re-evaluate the fallback whenever the BullMQ pin changes.
+- **PostgreSQL**: no raw-force branch. Against a blackholed host, `PostgresConnection.close()` settles when its configured 10-second connection timeout expires; the 11-second PostgreSQL budget awaits that promise instead of returning while its socket is still active. Worker's lock-renewal and stalled-check timers remain Worker-owned and use the same cleanup path on both backends.
+
+A raw ioredis connection (not a BullMQ owner) skips straight to a force-disconnect after its own bounded `quit()`/close attempt. Every step is best-effort — one step's error does not stop the ones after it — which is what keeps Node-RED shutdown and redeploy from hanging when the datastore is unreachable.
 
 ## Commands
 
-`lib/commands.js` maps `msg.cmd` to explicit BullMQ calls. It does not expose arbitrary method names. Legacy repeat commands call Job Scheduler APIs.
+`lib/commands.js` maps `msg.cmd` to explicit BullMQ v6 calls. It does not expose arbitrary method names or compatibility aliases.
 
 ## Schedulers
 
-`lib/scheduler.js` translates `msg.jobopts.repeat.cron` to `repeat.pattern` and requires a deterministic scheduler id. Scheduler lookup/removal uses exact ids.
+`lib/scheduler.js` serializes Job Scheduler metadata and requires an exact `msg.schedulerId`. Creation uses native `msg.repeat` and `msg.template` inputs.
 
 ## Workers And Acknowledgement
 
-`bull run` creates a BullMQ Worker.
+`bullmq run` creates a BullMQ Worker.
 
 - Immediate mode sends a Node-RED message and completes the job immediately.
-- Manual mode creates an opaque `msg.bull.ackId` and waits for a downstream `bull job` node.
+- Manual mode creates an opaque `msg.bull.ackId` and waits for a downstream `bullmq job` node.
+- Every worker defaults `maxStartedAttempts` to 100 so repeated non-failing transitions cannot reactivate one job forever.
 
 The in-process acknowledgement registry (`lib/acknowledgements.js`) stores live jobs and promise settlement functions. Each entry self-removes when it settles (complete, fail, timeout, or run-node close), so the registry does not accumulate finished jobs. Lock tokens are never sent in messages.
 
+### Cancellation
+
+`bullmq run` builds its processor with three arguments (`async (job, token, signal) => …`), which tells BullMQ to track a per-job `AbortController` for every job it runs, immediate or manual mode alike. `bullmq job`'s `cancelJob`/`cancelAllJobs` actions call `worker.cancelJob()`/`worker.cancelAllJobs()`, which abort that job's signal. `lib/acknowledgements.js` listens for the abort and fails the pending acknowledgement, so the worker's `await acknowledgement.entry.wait()` rejects and the job fails. BullMQ then applies the queue's normal attempts/backoff retry policy — cancellation only fails the current attempt, it does not remove the job.
+
+Both actions require the acknowledgement behind `msg.bull.ackId`, so they only reach manual-mode jobs that have not already settled.
+
 ## Events And Flows
 
-`bull events` wraps QueueEvents and emits event messages with `msg.topic`, `msg.payload`, and `msg.bull` metadata.
+`bullmq events` wraps QueueEvents and emits event messages with `msg.topic`, `msg.payload`, and `msg.bull` metadata.
 
-`bull flow` wraps FlowProducer and serializes the returned parent/child tree.
+`bullmq flow` wraps FlowProducer and serializes the returned parent/child tree, or the array of trees returned by `addBulk`.

package/docs/CHANGE_WORKFLOW.md

@@ -1,27 +1,26 @@
 # Change Workflow
 
+Constraints that apply to every change live in [RULES.md](RULES.md). This file is the procedure.
+
 ## Behavior Changes
 
-1. Read `GOAL.md` if present and the relevant docs in `docs/REFERENCE_MAP.md`.
+1. Read `GOAL.md` if present, then the owning file and test in [REFERENCE_MAP.md](REFERENCE_MAP.md).
 2. Add or update the smallest failing test.
 3. Run the focused test and confirm the expected failure.
 4. Implement the minimal change.
-5. Run the focused test and then `npm test`.
-6. Update README, node help, and docs when public behavior changes.
-7. Record unsupported BullMQ behavior with a reason instead of silently omitting it.
+5. Run the focused test, then `npm test && npm run format:check`.
+6. Update the README, the node help text, and the relevant `docs/` file when public behavior changes.
 
 ## Connection Changes
 
-Update `docs/CONNECTIONS.md` and tests in `test/connections.test.js`. Do not pass arbitrary ioredis options through messages or editor fields.
+Update [CONNECTIONS.md](CONNECTIONS.md) and `test/connections.test.js`. Run the Docker deployment matrix when it is available (see [TESTING.md](TESTING.md)); it covers the Redis topologies and both PostgreSQL fixtures.
+
+A change that touches shared connection code has to be checked on both backends, because they divide ownership differently: Redis connections are created here, PostgreSQL connections are owned by BullMQ. `test/redis-characterization.test.js` exists to catch drift in the Redis descriptors and options and must pass untouched; `npm run test:integration` runs the backend-neutral flows against both stores.
 
 ## Scheduler Changes
 
-Update `test/scheduler.test.js`. Legacy repeat behavior must use exact scheduler ids and must not call deprecated repeatable-job APIs.
+Update `test/scheduler.test.js`. Native Job Scheduler lookup and removal must keep using exact scheduler ids.
 
 ## Editor Changes
 
-Update `bull-queue.html`, static editor contract tests, and Playwright coverage. Credential fields must not export secrets in flow JSON.
-
-## Security
-
-Never commit MemoryDB credentials, Redis passwords, private keys, or generated TLS private keys.
+Update `bull-queue.html`, the static editor contract test, and Playwright coverage.

package/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # Command Reference
 
-`bull cmd` reads `msg.cmd`. It writes the command result to `msg.payload`.
+`bullmq cmd` reads `msg.cmd` and writes the command result to `msg.payload`.
 
 ## Jobs
 
@@ -15,6 +15,8 @@
 
 `add` uses `msg.jobName`, `msg.jobData` or `msg.payload`, and `msg.jobopts`.
 
+`add` and `addBulk` reject repeat options. Use `upsertJobScheduler` for repeating jobs.
+
 ## Delayed Jobs
 
 - `getDelayed`
@@ -24,6 +26,66 @@
 
 Add a delayed job with `msg.jobopts.delay`.
 
+One one-off job, delayed by 10 seconds:
+
+```js
+msg.cmd = "add";
+msg.jobName = "delayed";
+msg.jobData = { payload: "first" };
+msg.jobopts = { delay: 10000, removeOnComplete: true };
+return msg;
+```
+
+A series of one-off jobs, each delayed from the time the batch is added:
+
+```js
+msg.cmd = "addBulk";
+msg.payload = [
+  {
+    name: "delayed-1",
+    data: { payload: "first" },
+    opts: { delay: 10000, removeOnComplete: true },
+  },
+  {
+    name: "delayed-2",
+    data: { payload: "second" },
+    opts: { delay: 20000, removeOnComplete: true },
+  },
+  {
+    name: "delayed-3",
+    data: { payload: "third" },
+    opts: { delay: 30000, removeOnComplete: true },
+  },
+];
+return msg;
+```
+
+These are ordinary jobs, not schedulers. Increasing delays make them eligible in sequence; worker availability and concurrency determine their actual start times.
+
+For a series with exact date-times, convert each ISO-8601 timestamp to a delay when enqueueing:
+
+```js
+const schedule = [
+  { at: "2030-01-01T09:00:00+11:00", payload: "first" },
+  { at: "2030-01-01T09:15:00+11:00", payload: "second" },
+  { at: "2030-01-01T09:30:00+11:00", payload: "third" },
+];
+const now = Date.now();
+
+msg.cmd = "addBulk";
+msg.payload = schedule.map(({ at, payload }, index) => ({
+  name: `scheduled-${index + 1}`,
+  data: { payload, scheduledFor: at },
+  opts: {
+    delay: Math.max(0, Date.parse(at) - now),
+    removeOnComplete: true,
+  },
+}));
+return msg;
+```
+
+Use timestamps with an explicit `Z` or numeric UTC offset. A past timestamp becomes immediately eligible. Delayed jobs are eligible at the requested time, but worker availability still determines when processing starts.
+
 ## Priorities
 
 - `getPrioritized`
@@ -41,35 +103,34 @@ Add deduplication options through `msg.jobopts.deduplication`.
 
 ## Job Schedulers
 
-Native:
-
 - `upsertJobScheduler`
 - `getJobScheduler`
 - `getJobSchedulers`
 - `getJobSchedulersCount`
 - `removeJobScheduler`
 
-Legacy aliases:
+`upsertJobScheduler` uses `msg.schedulerId`, `msg.repeat`, and `msg.template`. Use `msg.repeat.pattern` for cron expressions and `msg.repeat.tz` for a timezone. Lookup and removal are exact-id based through `msg.schedulerId`.
 
-- `add` with `msg.jobopts.repeat`
-- `count`
-- `getRepeatableJobs`
-- `getRepeatableJobByKey`
-- `removeRepeatableByKey`
-
-Legacy lookup/removal is exact-id based.
+Removed repeatable-job command names fail with an error naming their BullMQ v6 replacement; see [MIGRATION.md](MIGRATION.md).
 
 ## Queue Administration
 
 - `getJobCounts`
 - `pause`
 - `resume`
+- `isPaused`
+- `isMaxed`
 - `drain`
 - `clean`
 - `stopAndRemoveAllJobs`
+- `getVersion`
 
 `stopAndRemoveAllJobs` removes schedulers, drains waiting/delayed jobs, and cleans inactive states. It does not claim to safely remove active jobs.
 
+`getJobCounts` no longer includes a `paused` key in its result: BullMQ v6 removed the `paused` job state, so a paused queue's jobs count as `waiting`. Use `isPaused` to check whether the queue itself is paused.
+
+`isPaused` and `isMaxed` each return a boolean for the queue's current state. `getVersion` returns the BullMQ version recorded against this queue in the backing store.
+
 ## Concurrency And Rate Limits
 
 - `setGlobalConcurrency`

package/docs/CONNECTIONS.md

@@ -1,18 +1,73 @@
 # Connection Guide
 
+BullMQ v6 stores a queue in either Redis or PostgreSQL. Each `bullmq-queue-server` config node picks one with **Backend**; everything below the Redis heading applies to the Redis backend only, and the PostgreSQL section states what changes.
+
 ## Standalone Redis
 
 Use deployment `single`, host, port, optional database, optional username/password, and optional TLS.
 
-Producer commands use bounded retries so Node-RED input handlers fail instead of hanging forever. Workers and QueueEvents use persistent retry behavior required by BullMQ.
+Producer commands fail fast so a Node-RED input handler errors instead of hanging forever: the BullMQ owner sets `skipWaitingForReady: true` and the socket keeps `maxRetriesPerRequest: 1`, which rejects in about a second when Redis is down. Workers and QueueEvents use the persistent retry behavior BullMQ requires (`maxRetriesPerRequest: null`).
+
+The offline queue stays enabled for producers too, which departs from BullMQ's production guide. Disabling it does fail faster, but it also rejects messages emitted during the brief connection window after a Node-RED deploy.
+
+Every data connection reconnects with exponential backoff floored at 1s and capped at 20s, which is what [BullMQ's production guide](https://docs.bullmq.io/guide/going-to-production) recommends. Cluster discovery uses the same range through `clusterRetryStrategy`, and Sentinel discovery uses it through `sentinelRetryStrategy`.
+
+## PostgreSQL
+
+Select backend `postgres`. The connection uses **Host**, **Port** (5432), **Database Name**, **Username**, the password credential, and three PostgreSQL-only fields: **Schema**, **Pool Max**, and **Migrations**. BullMQ owns every PostgreSQL connection — a pool per backend plus one dedicated `LISTEN` client for each Worker and QueueEvents backend — so this package creates none of its own on that path, and there is no raw client to reach for.
+
+A blank **Username** or **Database Name** is not "no value": node-postgres falls back to the `PGUSER`/`PGDATABASE` environment variables and then to the operating-system user name, so a blank field takes its value from the Node-RED process's environment. Set both explicitly unless that fallback is deliberate.
+
+`pg` is an optional peer dependency and is not installed with this package. Install it separately (`npm install pg`) before selecting the backend. BullMQ lazily requires it while constructing a queue, so a missing install is reported once per config node on first use, naming the command to run, rather than at load.
+
+PostgreSQL 13 is the floor BullMQ enforces and 14 is what it recommends; an older server is rejected with its version named. The server version is checked on connect, so a downgrade is reported rather than discovered mid-job.
+
+### Schema
+
+BullMQ's tables live in a schema, `bullmq` by default. Separate schemas keep independent queue sets in one database, and the schema name is validated before any I/O — an invalid name throws out of the queue constructor rather than reaching the server.
+
+### Migrations
+
+**Migrations** on (the default) runs BullMQ's migrator when the connection is first established, which issues `CREATE SCHEMA IF NOT EXISTS` and brings the schema to the version this BullMQ release expects. It is safe with several queues, workers, and event listeners starting at once: the migrator takes a PostgreSQL advisory lock, so concurrent starts converge on one migration rather than racing.
+
+Turn it off where the database user is not permitted to change the schema, and apply BullMQ's migrations out of band. A queue pointed at a database whose schema is missing or outdated then reports that as an actionable error naming the schema, not a stack trace, and the node stays usable.
+
+### Pool sizing
+
+**Pool Max** is the maximum connections in _each_ pool, defaulting to 2. Blank means the default; `0` is rejected, because a pool that can never hand out a connection cannot run a queue.
+
+There is one pool per BullMQ resource, not one per config node. BullMQ builds a fresh pool for every `Queue`, `Worker`, `QueueEvents`, and `FlowProducer`; Worker and QueueEvents also establish one dedicated `LISTEN` connection outside their pools. A config node feeding one `bullmq cmd`, one `bullmq run`, one `bullmq events`, and one `bullmq flow` therefore costs up to 4 × **Pool Max** + 2 server connections — 10 at the default.
+
+Unlike Redis, PostgreSQL has a hard server-wide ceiling — `max_connections`, commonly 100, shared with every other client. Multiply the figure above by every config node and every Node-RED instance pointed at the database before assuming headroom. Raise `max_connections`, or put a pooler in front, rather than guessing.
+
+node-postgres applies the same 10-second connection timeout to waiting for a free pooled connection as it does to opening a new one. A saturated pool can therefore fail an operation with `timeout exceeded when trying to connect` rather than merely running slower. Worker **Concurrency** does not require a one-to-one pool size: each database operation releases its client. Start with the default, raise **Pool Max** only when observed pool waits justify it, then check the total against `max_connections`.
+
+### TLS
+
+The shared TLS fields apply: enabling **TLS** builds the `ssl` object node-postgres receives, with the CA, client certificate, client key, and verification settings. One difference from Redis: node-postgres derives the TLS server name from the connection host when that host is a hostname, so **TLS Server Name** takes effect only when **Host** is a literal IP address.
+
+### What PostgreSQL does not have
+
+- No Cluster and no Sentinel. Those are Redis topologies; **Deployment** is hidden for PostgreSQL, and high availability is the database's own concern.
+- No key prefix. `prefix` is a Redis key-namespacing concept and is not sent, so the hash-tag rules below do not apply.
+- No raw client access, which is why shutdown differs — see the PostgreSQL step in [ARCHITECTURE.md](ARCHITECTURE.md#shutdown).
+- Three operations in BullMQ 6.3.1's PostgreSQL adapter throw `operation '...' is not implemented yet`: `trimEvents`, `removeDeprecatedPriorityKey`, and `paginate` for anything other than a flow's `:dependencies` and `:processed` keys. None is on a path these nodes use today.
+- Event rows are never trimmed. The adapter's `publishEvent` ignores the `maxEvents` argument, so the events table grows for as long as the queue is used. Prune it out of band if a flow leans on `bullmq events`.
+- BullMQ's own PostgreSQL documentation reports lower job-processing throughput than Redis, with `addBulk` close to parity. Treat Redis as the faster backend for high job rates and PostgreSQL as the one that removes a second datastore from the deployment.
+
+## Production Redis Configuration
+
+Redis must use `maxmemory-policy=noeviction`; evicting arbitrary BullMQ keys can corrupt queue behavior. Redis data must also be durable. For self-managed Redis, BullMQ recommends Append Only File (AOF) persistence, commonly with writes flushed once per second. For managed Redis, enable the provider's durable persistence and backup features appropriate to the job-loss tolerance of the deployment.
 
 ## Redis Cluster
 
-Use deployment `cluster` and provide startup nodes as comma or newline separated `host:port` values.
+Use deployment `cluster` and provide startup nodes as a comma- or newline-separated endpoint list.
 
-Cluster auth and TLS are applied through ioredis `redisOptions`. The runtime sets a DNS lookup passthrough for TLS-enabled cluster discovery.
+Cluster auth and TLS are applied through ioredis `redisOptions`. The runtime always sets a DNS lookup passthrough for cluster discovery, including non-TLS deployments.
 
-The BullMQ prefix must contain a Redis hash tag, normally `{bull}`. Untagged Cluster prefixes are rejected to prevent `CROSSSLOT` failures.
+The BullMQ prefix must contain a Redis hash tag. Untagged Cluster prefixes are rejected to prevent `CROSSSLOT` failures.
+
+`{bull}` is the default. Independent queues may use different tagged prefixes — `{orders}`, `{emails}` — to spread load across cluster nodes. Prefixes used in one `bullmq flow` tree or `FlowProducer.addBulk` batch must instead contain the same Redis hash tag because BullMQ updates those queues atomically and all involved keys must share a slot. Exact prefixes may differ, such as `{flow}:orders` and `{flow}:emails`; each worker must use the exact prefix assigned to its queue in the flow.
 
 ## AWS MemoryDB
 
@@ -41,14 +96,26 @@ Use deployment `sentinel` and configure:
 
 Sentinel authentication is separate from Redis data-node authentication.
 
+## Cluster And Sentinel Endpoint Lists
+
+Cluster startup nodes and Sentinel discovery lists accept host names, `host:port`, bare IPv6 with the default port, bracketed IPv6 such as `[2001:db8::1]:6379`, and `redis://` or `rediss://` URLs. Explicit URL schemes must agree with the applicable TLS setting: Cluster endpoints use `tls`, and Sentinel discovery endpoints use `sentinelTls`.
+
+URL credentials are rejected. Store Redis and Sentinel usernames/passwords in the config node credential fields instead of embedding them in an endpoint.
+
 ## TLS
 
-TLS options:
+TLS behavior and options:
 
-- verify unauthorized certificates by default;
+- rejects unauthorized certificates by default;
 - optional CA;
 - optional client certificate;
 - optional client private key;
 - optional server name.
 
-Disable verification only when the Redis deployment cannot be configured with a trusted CA and the risk is understood.
+These fields serve both backends. Disable verification only when the deployment cannot be configured with a trusted CA and the risk is understood.
+
+## Secrets And Imported Flows
+
+Passwords, CA data, client certificates, and private keys are read only from Node-RED credentials.
+
+BullMQ stores job names, payloads, results, and failure details in clear text, in Redis or in PostgreSQL alike. Avoid sensitive job data; when it is unavoidable, encrypt sensitive fields before sending the job to `bullmq cmd` or `bullmq flow` and decrypt them only in a trusted worker path.

package/docs/MIGRATION.md

@@ -1,37 +1,71 @@
-# Migration From Bull v4
+# Migration Guide
 
-## What Stays Compatible
+Package 2.0.0 is a breaking BullMQ v6 release. It does not register the old Bull node types or accept the old command, job-id, or repeatable-job aliases. Existing Bull v4 and BullMQ v5 queue data is not migrated.
 
-- Node types `bull-queue-server`, `bull cmd`, and `bull run`.
-- Message-driven `msg.cmd` command dispatch.
-- `msg.payload` compatibility for added jobs and worker output.
-- `msg.jobopts.repeat.cron` for scheduled jobs.
+## Before Upgrading
 
-## What Changes
+- Drain or otherwise account for Bull v4 jobs.
+- While still running the previous BullMQ package version, remove its repeatable-job definitions.
+- Export flows before changing node types and message shapes.
 
-- Runtime dependency is BullMQ 5.80.2.
-- `bull` and `sprintf-js` are removed.
-- Repeatable jobs use BullMQ Job Schedulers.
-- Scheduled jobs require a stable scheduler id.
-- `bull run` uses BullMQ Worker instead of Bull v4 `queue.process`.
+Bull and BullMQ do not provide a supported Redis data migration contract. Do not assume existing delayed, waiting, active, completed, or repeatable keys are usable after this upgrade.
 
-## Repeat Jobs
+## Flow Changes
 
-Legacy:
+Rename every node type:
+
+| Old type            | BullMQ v6 type        |
+| ------------------- | --------------------- |
+| `bull-queue-server` | `bullmq-queue-server` |
+| `bull cmd`          | `bullmq cmd`          |
+| `bull run`          | `bullmq run`          |
+| `bull job`          | `bullmq job`          |
+| `bull events`       | `bullmq events`       |
+| `bull flow`         | `bullmq flow`         |
+
+Replace `msg.command` with `msg.cmd` and `msg.jobid` with `msg.jobId`; the removed fields now produce explicit errors. Removed repeatable aliases have these native replacements:
+
+| Removed command          | BullMQ v6 command       |
+| ------------------------ | ----------------------- |
+| `getRepeatableJobs`      | `getJobSchedulers`      |
+| `count`                  | `getJobSchedulersCount` |
+| `getRepeatableJobByKey`  | `getJobScheduler`       |
+| `removeRepeatableByKey`  | `removeJobScheduler`    |
+| `add` with `opts.repeat` | `upsertJobScheduler`    |
+
+Job Scheduler lookup and removal require the exact id in `msg.schedulerId`.
+
+## Scheduler Shape
+
+Replace the old repeat shape:
 
 ```js
+msg.cmd = "add";
 msg.jobopts = {
-  jobId: msg.payload,
-  repeat: { cron: "30 9,19,29,39,49,59 * * * *" },
+  jobId: "heartbeat",
+  repeat: { cron: "*/1 * * * *", utc: true },
+};
+```
+
+with BullMQ v6 inputs:
+
+```js
+msg.cmd = "upsertJobScheduler";
+msg.schedulerId = "heartbeat";
+msg.repeat = { pattern: "*/1 * * * *", tz: "UTC" };
+msg.template = {
+  name: "heartbeat",
+  data: { payload: "scheduled heartbeat" },
 };
 ```
 
-Runtime translation:
+Use `pattern`, not `cron`, and `tz`, not `utc`.
 
-- scheduler id: `msg.schedulerId` or `msg.jobopts.jobId`;
-- repeat pattern: `msg.jobopts.repeat.pattern`;
-- template data: `msg.jobData` or `{ payload: msg.payload }`.
+## Other BullMQ v6 Changes
 
-## Data Migration
+- `job.getState()` no longer returns `paused`; jobs in a paused queue report `waiting`. Use `isPaused` for the queue state.
+- `getJobCounts` no longer includes a `paused` key.
+- Flow children without an explicit `opts.jobId` receive UUIDs rather than incremental numeric ids.
+- The default event filter includes `retries-exhausted`.
 
-Bull v4 and BullMQ do not provide a supported Redis data migration contract. Do not assume existing delayed, waiting, active, completed, or repeatable Bull v4 keys will be usable by BullMQ.
+After updating flows, run them against a non-production Redis deployment before upgrading production.

package/docs/NODE_GUIDE.md

@@ -1,35 +1,50 @@
 # Node Guide
 
-## `bull-queue-server`
+## `bullmq-queue-server`
 
-Configures queue name, Redis deployment, credentials, TLS, and BullMQ prefix.
+Configures queue name, backend, connection, credentials, and TLS.
 
-Deployment modes:
+`backend` selects where BullMQ stores the queue. Absent or blank means `redis`, so a flow saved before the field existed keeps working unchanged.
+
+- `redis`: the deployment modes, key prefix, and Redis database number below.
+- `postgres`: `database`, `schema`, `max` (pool size), and `migrate` instead. Needs the optional peer dependency `pg` installed. See [CONNECTIONS.md](CONNECTIONS.md#postgresql).
+
+Deployment modes (Redis only; hidden for `postgres`):
 
 - `single`: standalone Redis.
 - `cluster`: Redis Cluster and AWS MemoryDB.
 - `sentinel`: Redis Sentinel.
 
-Cluster and MemoryDB prefixes must contain a Redis hash tag; use `{bull}` unless you have a tested custom hash tag.
+Redis only. Cluster and MemoryDB prefixes must contain a Redis hash tag. `{bull}` is the default. Independent queues may use different tags — `{orders}`, `{emails}` — to spread load across cluster nodes. Prefixes in one `bullmq flow` tree or bulk flow batch must contain the same hash tag so their atomic Redis operations stay in one slot. Each worker must use the exact prefix assigned to its queue in the flow.
+
+`removeOnComplete` and `removeOnFail` set queue-level auto-removal as BullMQ `defaultJobOptions`, keeping that many of the newest jobs in each state. New config nodes default to keeping 1000 completed and 5000 failed jobs. A blank field keeps every job, which is BullMQ's own default and grows the backing store without bound.
+
+For `bullmq cmd`, `msg.jobopts` overrides these defaults. For `bullmq flow`, the defaults apply to every queue named in the flow tree; `msg.flowopts.queuesOptions[queueName].defaultJobOptions` overrides the config for one queue, and the job's own `opts` has final precedence.
+
+Optional OpenTelemetry fields `telemetry`, `telemetryServiceName`, and `telemetryMetrics` are off/blank by default; see [docs/TELEMETRY.md](TELEMETRY.md).
 
-## `bull cmd`
+## `bullmq cmd`
 
 Input node for producer and administration commands.
 
 Input:
 
 - `msg.cmd`: command name. Defaults to `add`.
-- `msg.payload`: compatibility payload.
+- `msg.payload`: job data for `add` when `msg.jobData` is not supplied, or command input where documented.
 - `msg.jobData`: full BullMQ job data when supplied.
 - `msg.jobName`: BullMQ job name. Defaults to `default`.
 - `msg.jobopts`: BullMQ job options.
 
+`add` and `addBulk` reject repeat options. Use the native Job Scheduler commands and fields documented in [docs/COMMANDS.md](COMMANDS.md).
+
 Output:
 
 - successful result in `msg.payload`;
 - errors go to `done(err)` or `node.error(err, msg)`.
 
-## `bull run`
+BullMQ v6 removed the `paused` job state: `getJobState` never returns `"paused"` (a paused queue's jobs report `"waiting"`), and `getJobCounts` no longer has a `paused` key. Use `isPaused` to check the queue itself.
+
+## `bullmq run`
 
 Worker node with no input and one output.
 
@@ -42,9 +57,11 @@ Output message:
 Completion modes:
 
 - `immediate`: complete after sending the message.
-- `manual`: wait for downstream `bull job` acknowledgement. Fails the job after the ack timeout; set the timeout to `0` to wait indefinitely.
+- `manual`: wait for downstream `bullmq job` acknowledgement. Fails the job after the ack timeout; set the timeout to `0` to wait indefinitely.
 
-## `bull job`
+Concurrency and Max Started Attempts must be positive integers. Max Started Attempts defaults to 100 and bounds reprocessing loops from transitions that do not increment `attemptsMade`, including `moveToWait` and `moveToDelayed`. BullMQ fails the job unrecoverably before its processor runs for the 101st time. The optional limiter maximum and duration must either both be blank or both be positive integers.
+
+## `bullmq job`
 
 Acts on manual-mode active jobs. Actions can be configured or supplied in `msg.cmd`.
 
@@ -62,10 +79,27 @@ Non-terminal actions:
 - `getChildrenValues`
 - `getFailedChildrenValues`
 - `removeUnprocessedChildren`
+- `updateData`: replaces the job's stored data with `msg.jobData`, falling back to `msg.payload`. The new data survives a retry, so it is how a flow records which step a job reached.
+
+Step and retry transitions. Each hands the job's lock token back to BullMQ, so the job leaves the active state without counting a failed attempt, and the flow's acknowledgement is settled for it:
 
-## `bull events`
+- `moveToWait`: requeues the job to be picked up again. This is BullMQ's manual-retry pattern.
+- `moveToDelayed`: delays the job by `msg.delay` milliseconds and resumes it later. Requires `msg.delay`.
 
-QueueEvents source node. Empty event filter subscribes to the default documented event list.
+Together with `updateData` these implement BullMQ's process-step-jobs pattern: record the step, then requeue or delay the job, and resume at that step on its next activation. The lock token these need never appears in a Node-RED message.
+
+Cancellation actions (BullMQ v6 cooperative cancellation):
+
+- `cancelJob`: cancels the active job identified by `msg.bull.ackId`. Reason comes from `msg.reason`, default `"BullMQ job cancelled"`. Outputs `true`. If BullMQ reports the job as no longer cancellable, the node raises an error naming the job id instead of sending a message.
+- `cancelAllJobs`: cancels every active manual-mode job on the `bullmq run` node that owns `msg.bull.ackId`. Same `msg.reason` default. Always outputs `true`.
+
+Both actions are acknowledgement-scoped: like every `bullmq job` action, they act on the job behind `msg.bull.ackId`, so they only work for manual-completion jobs that have not yet settled (completed, failed, or timed out). Cancelling aborts the worker's per-job signal, which fails the pending acknowledgement; BullMQ then applies the queue's normal attempts/backoff retry policy to the job. Cancellation does not itself complete or remove the job.
+
+## `bullmq events`
+
+QueueEvents source node. An empty event filter subscribes to: `active`, `added`, `cleaned`, `completed`, `deduplicated`, `delayed`, `drained`, `duplicated`, `failed`, `paused`, `progress`, `removed`, `resumed`, `retries-exhausted`, `stalled`, `waiting`, and `waiting-children`.
+
+`retries-exhausted` is new in 2.0.0. A flow already deployed with an empty event filter now receives this extra event type without any config change.
 
 Output:
 
@@ -73,11 +107,15 @@ Output:
 - `msg.payload`: BullMQ event payload;
 - `msg.bull`: queue, event, and event id metadata.
 
-## `bull flow`
+## `bullmq flow`
 
 Adds a BullMQ FlowProducer tree.
 
 Input:
 
-- `msg.payload`: BullMQ flow tree;
-- `msg.flowopts`: optional FlowProducer options.
+- `msg.payload`: a BullMQ flow tree, or an array of flow trees;
+- `msg.flowopts`: optional FlowProducer options, for a single tree.
+
+An array uses `FlowProducer.addBulk`, which atomically creates multiple independent root trees: every tree is added or none is. Use one flow tree when jobs are related by parent/child dependencies, even when that tree spans queues. `msg.flowopts` does not apply to an array, because `addBulk` takes no options argument; queue-level auto-removal is stamped onto each job's own `opts` instead, where anything the tree already sets wins. On Redis Cluster, omit each flow job's `prefix` to use the flow node's prefix throughout. If prefixes are set per job, they must contain the same hash tag, and each worker must use its queue's exact prefix. An empty array is an error.
+
+A child job in the tree that does not set `opts.jobId` gets a UUID as its job id (BullMQ v6 no longer assigns incremental numeric ids). Set `opts.jobId` on a child explicitly if the flow depends on a stable or predictable id.