oxen-queue-v2

library3.0.0jsnpmunverified

A resilient worker queue backed by MySQL. Version 3.0.0. Provides job persistence, priority, deduplication, concurrency, delayed jobs, and multi-process/server operation. Designed for high-throughput jobs (millions per day) with strong resilience to misbehaving jobs and dropped connections. Differentiators: leverages MySQL for queries and persistence, no additional infrastructure needed; dual ESM/CJS build with full TypeScript types. Not suitable for sub-second latency user-facing jobs. Released under MIT license.

database

npm install oxen-queue-v2

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OXEN-QUEUE-V2

oxen-queue-v2

databasejavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Queue

✓ import { Queue } from 'oxen-queue-v2'

✗ import Queue from 'oxen-queue-v2'

Queue is a named export, not default. Also available via require: const { Queue } = require('oxen-queue-v2').

QueueConfig

✓ import { QueueConfig } from 'oxen-queue-v2'

✗ import { Config } from 'oxen-queue-v2'

Type export for configuration object. Only available in TypeScript.

Job

✓ import { Job } from 'oxen-queue-v2'

✗ import Job from 'oxen-queue-v2'

Type export representing a job object. Named export, not default.

Initializes the queue, creates the MySQL table, adds a job, and sets up a worker process.

import { Queue } from 'oxen-queue-v2'; const queue = new Queue({ mysqlConfig: { host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'test' } }); // Create the queue table (run once) await queue.createTable(); // Add a job await queue.addJob({ body: { message: 'Hello World' }, priority: 5 }); // Process jobs queue.process(async (job, done) => { console.log('Processing job:', job.id, job.body); // Do work... done(); });

Debug

Known issues

breakingv3.0.0 requires MySQL 8.0+ due to use of window functions.

fix

Ensure MySQL server version is 8.0 or higher.

affects: >=3.0.0

breakingv3.0.0 drops support for Node.js <14. Engine requirement changed from >=12 to >=14.

fix

Upgrade Node.js to version 14 or higher.

affects: >=3.0.0

deprecatedThe 'createTable' method is deprecated and will be removed in v4. Use 'Queue.createSchema' instead.

fix

Replace queue.createTable() with Queue.createSchema(mysqlConfig).

affects: >=3.0.0

gotchaJob deduplication relies on the 'uniqueKey' field; jobs with the same uniqueKey will be deduplicated even if other fields differ.

fix

Set uniqueKey to null or omit it explicitly if you do not want deduplication.

affects: >=1.0.0

gotchaDefault concurrency is 1. To increase concurrency, set the 'concurrency' option in configuration.

fix

Pass { concurrency: 5 } in the Queue constructor options.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Connection lost: The server closed the connection.

MySQL idle timeout or network issue; Oxen does not auto-reconnect by default.

fix

Enable auto-reconnect in the mysqlConfig: { connectionLimit: 10, waitForConnections: true, enableKeepAlive: true }.

TypeError: queue.addJob is not a function

Using a default import instead of named import.

fix

Use import { Queue } from 'oxen-queue-v2' instead of import Queue from 'oxen-queue-v2'.

Error: Table 'oxen_queue' doesn't exist

Queue table has not been created yet.

fix

Call await queue.createTable() (or the newer Queue.createSchema) before using the queue.

Error: ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server

MySQL 8 default authentication plugin is caching_sha2_password, but the mysql2 client may need configuration.

fix

In mysqlConfig, set { authPlugins: { caching_sha2_password: true } } or use 'mysql_native_password' user.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver for queue storage and operations

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/necessarylion/oxen-queue-v2 ↗

packageoxen-queue-v2 ↗

homepagehttps://github.com/necessarylion/oxen-queue-v2#readme ↗