pg-boss

library12.18.2jsnpmunverified

pg-boss is a PostgreSQL-based job queue for Node.js providing exactly-once delivery, backpressure-compatible polling, cron scheduling, dead letter queues, priority queues, and automatic retries with exponential backoff. It uses PostgreSQL's SKIP LOCKED to guarantee atomic commits and can create jobs within existing database transactions. Ships TypeScript types, supports multi-master deployments (e.g., Kubernetes ReplicaSet), serverless functions, and CLI for migrations. Version 12.18.2 requires Node >=22.12.0. Key differentiators: SQL-based operations, ORM transaction adapters (Knex, Kysely, Prisma), and pub/sub API for fan-out patterns.

database devops

npm install pg-boss

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-BOSS

pg-boss

databasejavascriptv12.18.2

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.

PgBoss

✓ import { PgBoss } from 'pg-boss'

✗ import PgBoss from 'pg-boss'

PgBoss is a named export, not a default export. CommonJS: const { PgBoss } = require('pg-boss').

fromKnex

✓ import { fromKnex } from 'pg-boss'

✗ import { fromKnex } from 'pg-boss/adapter'

Adapters are exported from the main 'pg-boss' package since v8. Do not import from subpaths.

WorkHandler

✓ import type { WorkHandler } from 'pg-boss'

✗ import { WorkHandler } from 'pg-boss'

WorkHandler is a TypeScript type, not a runtime value. Use type-only import.

Shows basic setup: create PgBoss instance, start, create queue, send job, work callback.

import { PgBoss } from 'pg-boss'; async function main() { const boss = new PgBoss('postgres://user:pass@localhost:5432/mydb'); boss.on('error', err => console.error(err)); await boss.start(); const queue = 'email-queue'; await boss.createQueue(queue); const jobId = await boss.send(queue, { to: 'user@example.com', subject: 'Hello' }); console.log(`Created job ${jobId}`); await boss.work(queue, async ([job]) => { console.log(`Processing job ${job.id}: ${JSON.stringify(job.data)}`); }); console.log('Worker started. Press Ctrl+C to stop.'); } main().catch(err => { console.error(err); process.exit(1); });

Debug

Known issues

breakingVersion 8+ changed exports from default to named (PgBoss). Old import PgBoss from 'pg-boss' fails.

fix

Use import { PgBoss } from 'pg-boss' instead of default import.

affects: >=8.0.0

breakingVersion 12 drops support for Node versions below 22.12.0.

fix

Upgrade Node.js to >=22.12.0 or use pg-boss@11.x.

affects: >=12.0.0

gotchaCalling start() before sending jobs is required; missing start() leads to silent failures.

fix

Always await boss.start() before boss.send() or boss.work().

affects: >=1.0.0

deprecatedThe method 'publish()' is deprecated in favor of 'send()' since version 6.

fix

Replace boss.publish() with boss.send().

affects: >=6.0.0

gotchaIf you omit 'error' event listener, unhandled errors may crash the process.

fix

Attach an 'error' listener: boss.on('error', console.error).

affects: >=1.0.0

breakingAdapter imports (fromKnex, fromKysely, fromPrisma) moved to main package in v8. Importing from subpaths breaks.

fix

Import adapters from 'pg-boss' directly, not from 'pg-boss/adapters'.

affects: >=8.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED ::1:5432

PostgreSQL not running or connection string incorrect.

fix

Verify PostgreSQL is running and connection string is correct: 'postgres://user:pass@host:port/db'.

TypeError: boss.send is not a function

Using default import (PgBoss) instead of named import { PgBoss }.

fix

Change import to: import { PgBoss } from 'pg-boss'.

ERROR: relation "pgboss.job" does not exist

pg-boss schema not initialized. start() or migration command missing.

fix

Run `await boss.start()` or `npx pg-boss migrate` to create required tables.

Error: Cannot find module 'pg-boss'

pg-boss not installed or wrong import path.

fix

Run `npm install pg-boss` and ensure import path is correct.

TypeError: adapter must be a function

Passing import module directly instead of calling adapter factory.

fix

Use fromKnex(trx) not fromKnex(trx) — call the adapter function with the transaction object.

Upgrade

Version history

12.18.2latest on npm

Audit

Dependencies

pgrequiredPostgreSQL client library — required for all database interactions

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/timgit/pg-boss ↗

packagepg-boss ↗

homepagehttps://timgit.github.io/pg-boss ↗