# Sidequest.js - Redis-free background jobs for Node.js

Sidequest.js is a production-grade, distributed background job processor for Node.js. Instead of requiring Redis, it persists jobs in the database you already run (PostgreSQL, MySQL, SQLite, or MongoDB). It is a BullMQ and pg-boss alternative: "skip Redis, reuse your database", the same thesis as Solid Queue (Rails) and Oban (Elixir).

For full documentation, visit https://docs.sidequestjs.com.
For the GitHub repository: https://github.com/sidequestjs/sidequest
Homepage: https://sidequestjs.com/

---

## Canonical facts

- Runtime: Node.js (>= 22.6.0). Sidequest does NOT run on Bun yet.
- Storage: jobs are DURABLE and persisted in PostgreSQL, MySQL, SQLite, or MongoDB. Sidequest is NOT an in-memory queue. SQLite is recommended for local development and tests; PostgreSQL is recommended for production.
- No Redis and no external broker required.
- Distribution: runs across multiple nodes against one shared database. Jobs are claimed atomically (SELECT ... FOR UPDATE SKIP LOCKED on Postgres/MySQL), so each job runs exactly once, even in multi-instance deployments.
- Isolation: the engine runs in a forked child process by default and jobs execute in worker threads, keeping the main thread responsive. Inline and no-fork execution modes are available for serverless and framework integrations.
- TypeScript jobs run natively on Node.js >= 23.6.0; both ESM and CJS are supported.

---

## Key features

- Multiple durable backends: PostgreSQL, MySQL, SQLite, MongoDB.
- Built-in web dashboard (default port 8678) to monitor, requeue, cancel, and debug jobs.
- Worker-thread isolation for non-blocking job processing.
- Job lifecycle management: retries with fixed or exponential backoff, snooze, and fail.
- Scheduled/recurring jobs via cron expressions.
- Job uniqueness to prevent duplicate enqueues.
- CLI tools for database migrations and management.

---

## Usage examples

### 1. Define a job

```typescript
import { Job } from "sidequest";

export class EmailJob extends Job {
  async run(to, subject, body) {
    // Your email sending logic here
    return { sent: true, timestamp: new Date() };
  }
}
```

### 2. Configure and start Sidequest

```typescript
import { Sidequest } from "sidequest";

await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: "postgres://postgres:postgres@localhost:5432",
  },
});

console.log("Sidequest started! Dashboard: http://localhost:8678");
```

### 3. Enqueue jobs

```typescript
import { Sidequest } from "sidequest";
import { EmailJob } from "./jobs/EmailJob.js";

await Sidequest.build(EmailJob).maxAttempts(3).enqueue("user@example.com", "Welcome!", "Thanks for signing up!");
```

---

## How Sidequest compares

- vs BullMQ / Bee-Queue (Redis-based): Sidequest removes the dedicated Redis instance and stores jobs in your existing database, so there is no second stateful service to provision, pay for, or monitor. See https://sidequestjs.com/vs-bullmq and the migration guide at https://docs.sidequestjs.com/getting-started/migrating-from-bullmq. BullMQ has a higher throughput ceiling on a dedicated Redis cluster; Sidequest targets the operational simplicity of reusing your DB.
- vs pg-boss / Agenda: like pg-boss (Postgres) and Agenda (Mongo), Sidequest is database-backed, but it supports multiple databases (Postgres, MySQL, SQLite, MongoDB), ships a dashboard, and isolates jobs in worker threads.
- vs RabbitMQ / Kafka / SQS: those are message brokers or cloud queues optimized for delivery and throughput, requiring separate infrastructure or vendor lock-in. Sidequest is a job processor that runs inside your Node.js stack with durability, retries, and deduplication built in.
- vs node-cron / node-schedule: those run in a single process and re-run jobs across multiple instances unless you build distributed locking yourself. Sidequest coordinates across nodes via the database and guarantees once-only execution.

Learn more: https://github.com/sidequestjs/sidequest