pg-boss: PostgreSQL Job Queue for Node.js

pg-boss is a job queue built in Node.js on top of PostgreSQL, providing background processing and reliable asynchronous execution. It leverages PostgreSQL's SKIP LOCKED feature for exactly-once delivery, ensuring safe record locking and guaranteed atomic commits. It is designed for teams familiar with relational database semantics (SQL, querying, backups) and aims to reduce architectural complexity by using PostgreSQL as the sole queue backend.

Sources: docs/README.md

pg-boss is a job queue powered by PostgreSQL, operated by one or more Node.js instances. It leverages PostgreSQL's SKIP LOCKED feature to resolve record locking challenges inherent with relational databases, providing exactly-once delivery and guaranteed atomic commits for asynchronous job processing.

This library is ideal for teams familiar with relational database semantics (SQL, querying, backups) who want to minimize the number of systems required to monitor and support their architecture.

• Delete: Use deleteJob(name, id) to remove a job during processing.
• Resume: Move a cancelled job back to created using resume(name, id).
• Retry: Manually retry a failed job using retry(name, id).

Jobs that are not actively deleted will remain in completed, cancelled, or failed state until they are automatically removed by the system.

Sources: docs/introduction.md

The dashboard provides the following features for monitoring and managing pg-boss:

• Overview Dashboard: View aggregate statistics, problem queues, and recent warnings.
• Queue Management: Browse all queues with real-time stats (queued, active, deferred, total).
• Job Browser: View and manage individual jobs with smart filtering (defaults to pending jobs).
• Job Actions: Create, cancel, retry, resume, or delete jobs directly from the UI.
• Warning History: Track slow queries, queue backlogs, and clock skew issues.
• Multi-Database Support: Monitor multiple pg-boss instances from a single dashboard.

Sources: docs/dashboard.md

Deploy the dashboard using Docker:

Dockerfile:

FROM node:24
WORKDIR /app
RUN npm install -g @pg-boss/dashboard
ENV PORT=3000
EXPOSE 3000
CMD ["pg-boss-dashboard"]

Build and run:

docker build -t pgboss-dashboard .
docker run -d \
  -e DATABASE_URL="postgres://user:pass@host:5432/db" \
  -p 3000:3000 \
  pgboss-dashboard

This approach provides containerized deployment with automatic dependency management.

docker run -d -e DATABASE_URL="postgres://user:pass@host:5432/db" -p 3000:3000 pgboss-dashboard

Sources: packages/dashboard/README.md

To work on the dashboard from source:

# Clone the pg-boss repository
git clone https://github.com/timgit/pg-boss.git
cd pg-boss/packages/dashboard

# Install dependencies
npm install

# Initialize local database with pg-boss schema and test queues
npm run dev:init-db

# Start development server with hot reloading
npm run dev

# (Optional) Start a worker to process jobs
npm run dev:worker

# Build for production
npm run build

# Run production build
npm start

Notes:

• dev:init-db connects to postgres://postgres:postgres@127.0.0.1:5432/pgboss by default
• dev:worker runs in a separate terminal and stays running until stopped with Ctrl+C
• The worker processes jobs from the same pg-boss instance as the dashboard

npm run dev:init-db && npm run dev

Sources: packages/dashboard/README.md

For runtime-neutral usage (e.g., Deno, Bun, or custom environments), use createProxyService and manually wire shutdown listeners (see "Lifecycle Wiring by Runtime").

import { createProxyServerNode } from '@pg-boss/proxy/node'

const proxy = await createProxyServerNode()
await proxy.start()

Sources: packages/proxy/README.md