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
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
For applications whose data already lives in MySQL or MariaDB.
- Package@queuert/mysql
- Clientsmysql2
- LockingFOR UPDATE SKIP LOCKED
Redis
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
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
- TransactionsRun 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 jobsCreate 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 workClaim 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
- BlockersAdd 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 leasesRegister a worker with a lease, extend the lease while it is live, and delete the worker row on stop.startWorker extendWorkerLease stopWorker
- ReadsThe 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
configis 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.closereleases internal resources and is idempotent;[Symbol.asyncDispose]calls it, so an adapter can be held withawait using. On a"sync"adapter,closereturns nothing and[Symbol.dispose]calls it, so it is held withusing.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
undefinedin 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
tokenon the worker row; attempt-scoped writes need the job'sattemptToken, whichstartJobAttemptssets 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.