State Adapters

Where Queuert keeps chains, jobs and workers, and the StateAdapter interface every backend implements.

State adapters abstract database operations for job persistence. They handle job creation, status transitions, attempt tracking, and queries. Every option below implements the same StateAdapter interface, which createClient and createWorkerRunner consume.

PostgreSQL

recommended

Supports horizontal scaling and all Queuert features.

  • Package@queuert/postgres
  • Clientspg · postgres.js · Bun SQL · Drizzle · Kysely · Prisma · Knex · MikroORM
  • LockingFOR UPDATE SKIP LOCKED

SQLite

Suitable for local development, CLI tools, and embedded applications.

  • Package@queuert/sqlite
  • Clientsbetter-sqlite3 · node:sqlite · bun:sqlite · Bun SQL · Drizzle · Kysely · Prisma · Knex · MikroORM
  • Lockingsingle writer, writes serialized

MySQL / MariaDB

experimental

For applications whose data already lives in MySQL or MariaDB.

  • Package@queuert/mysql
  • Clientsmysql2
  • LockingFOR UPDATE SKIP LOCKED

Redis

experimental

Queuert's state on Redis or Redis Cluster, kept apart from your application data, which lives in another database.

  • Package@queuert/redis
  • Clientsioredis · node-redis
  • Lockingoptimistic, callbacks rerun on conflict

In-process

built-in

All state is held in memory and lost on process exit. For tests and single-process apps.

  • Packagequeuert
  • Clientsnone
  • Scopeone process

Custom

A StateAdapter of your own, for another database engine.

  • Packageyour own
  • Databaseany
  • Checked byqueuert/conformance

The StateAdapter interface

StateAdapter<TTxContext, TJobId, TWorkerId, TMode> is exported from queuert. Its type parameters are the transaction context type, the job ID type, the worker ID type and the required mode, "async" or "sync", which sets whether the methods return promises or plain values. Its members, by purpose:

StateAdapter

  • Transactions
    Run a callback in a transaction that commits on success and rolls back on error, tell whether a context is in an open transaction without a query, and run callbacks after the context's transaction commits or when it (or the savepoint the context belongs to) rolls back. The client and the worker register every side effect through these callbacks; see Tx Hooks.
    withTransaction isTransaction onTransactionCommit onTransactionRollback
  • Creating and finishing jobs
    Create chain heads (a deduplicated match comes back marked deduplicated), complete a job with its output or continue it with a successor, return jobs to pending (or move a blocked job's schedule), and delete chains.
    createJobs continueJobs completeJobs rescheduleJobs deleteChains
  • Claiming work
    Claim due jobs of the given types for a worker with a live lease, skipping locked rows so no two callers get the same job, and report how long until the next pending job is due.
    startJobAttempts getStartAttemptDelayMs
  • Blockers
    Add blocker chains to jobs, read a job's blockers, and move a completed chain's dependents to pending once all their blockers completed.
    addJobsBlockers getJobBlockers unblockJobs
  • Worker leases
    Register a worker with a lease, extend the lease while it is live, and delete the worker row on stop.
    startWorker extendWorkerLease stopWorker
  • Reads
    The lookups, counts and paginated lists behind the client's read-only methods and the dashboard.
    getChains getJobs getWorkers getChainTypeNames getJobTypeNames countChainsByTypeName countJobsByTypeName countWorkers countWorkersByTypeName countRunningJobsByWorkerId listChains listJobs listChainJobs listBlockedJobs listWorkers listWorkerJobs
  • Configuration and lifecycle
    config is how the adapter was configured, with defaults applied: the ID and limit settings used to generate and validate job and worker IDs and enforce the blocker limit. close releases internal resources and is idempotent; [Symbol.asyncDispose] calls it, so an adapter can be held with await using. On a "sync" adapter, close returns nothing and [Symbol.dispose] calls it, so it is held with using.
    config close [Symbol.asyncDispose] [Symbol.dispose]

Its "sync" mode, StateAdapter<TTxContext, TJobId, TWorkerId, "sync">, is for drivers that run statements synchronously: the same members, each returning its result directly, a withTransaction that runs a synchronous callback, sync: true, which tells Queuert the adapter's mode, and a close that returns nothing, with [Symbol.dispose] in place of [Symbol.asyncDispose], so the adapter is held with using. createClient and createWorkerRunner follow the adapter's mode, so a client over it returns plain values; SQLite ships one, see SQLite synchronous providers.

How adapters behave

  • Missing rows are not errors. An absent or already completed row is reported as undefined in the result position it belongs to, and the caller decides which error the user sees. Adapters still throw for driver errors and connection loss.
  • Lookups return results in input order. Lookups by ID return one entry per requested ID, in input order.
  • Constant round trips. The number of database operations a method executes does not depend on how many jobs it affects; array methods are batched, never looped.
  • Writes are fenced. Worker writes need the token on the worker row; attempt-scoped writes need the job's attemptToken, which startJobAttempts sets anew on every claim.

Transaction context

The transaction context (TTxContext) represents an active transaction: the one your own database client opened and passed to client.createChain or a handler's complete, or one opened by withTransaction. Besides the transaction handle, it may carry the txHooks a provider registers commit and rollback callbacks on; mutating calls and complete require every field of the context, and reads take any part of it. Queuert itself opens transactions only for migrations, for the worker's registration, reclaims and stop, and in test helpers, never around job processing.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open