node package manager


Queueing jobs in Node.js using PostgreSQL like a boss.

PostgreSql Version npm version Build Status Coverage Status Dependencies

const PgBoss = require('pg-boss');
const boss = new PgBoss('postgres://user:pass@host/database');
boss.on('error', onError);
function ready() {
  boss.publish('some-job', {param1: 'parameter1'})
    .then(jobId => console.log(`created some-job ${jobId}`))
  boss.subscribe('some-job', someJobHandler)
    .then(() => console.log('subscribed to some-job'))
function someJobHandler(job, done) {
  console.log(`received ${} ${}`);
  console.log(`data: ${JSON.stringify(}`);
    .then(() => console.log(`some-job ${} completed`))
function onError(error) {

pg-boss is a message queue (aka job queue, task queue) built in Node.js on top of PostgreSQL in order to provide guaranteed messaging and asynchronous execution to your Node apps.

Why would you consider using this queue over others? pg-boss was created to leverage recent additions in PostgreSQL 9.5 (specifically SKIP LOCKED and upserts) which significantly enhances its ability to act as a reliable, distributed message queue. I wrote this to remove a dependency on Redis (via the kue package), consolidating systems I have to support in production as well as upgrading to guaranteed message processing (you know, what Redis cannot offer you ;). This will likely cater to anyone already familiar with the simplicity of relational database semantics and operations (querying and backups, for example) as well as a low budget solution to a very common problem.


  • Guaranteed delivery and finalizing of jobs using a promise API
  • Delayed jobs
  • Job retries
  • Job throttling (singleton jobs and rate limiting)
  • Configurable worker concurrency
  • Distributed and/or clustered workers
  • Automatic provisioning of required storage into a dedicated schema
  • Automatic monitoring for expired jobs
  • Automatic archiving for completed jobs


  • Node 4 or higher
  • PostgreSQL 9.5 or higher


$ npm install pg-boss