{"id":43538,"library":"pg-boss","title":"pg-boss","description":"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.","status":"active","version":"12.18.2","language":"javascript","source_language":"en","source_url":"https://github.com/timgit/pg-boss","tags":["javascript","postgresql","postgres","queue","job","typescript"],"install":[{"cmd":"npm install pg-boss","lang":"bash","label":"npm"},{"cmd":"yarn add pg-boss","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-boss","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"PostgreSQL client library — required for all database interactions","package":"pg","optional":false}],"imports":[{"note":"PgBoss is a named export, not a default export. CommonJS: const { PgBoss } = require('pg-boss').","wrong":"import PgBoss from 'pg-boss'","symbol":"PgBoss","correct":"import { PgBoss } from 'pg-boss'"},{"note":"Adapters are exported from the main 'pg-boss' package since v8. Do not import from subpaths.","wrong":"import { fromKnex } from 'pg-boss/adapter'","symbol":"fromKnex","correct":"import { fromKnex } from 'pg-boss'"},{"note":"WorkHandler is a TypeScript type, not a runtime value. Use type-only import.","wrong":"import { WorkHandler } from 'pg-boss'","symbol":"WorkHandler","correct":"import type { WorkHandler } from 'pg-boss'"}],"quickstart":{"code":"import { PgBoss } from 'pg-boss';\n\nasync function main() {\n  const boss = new PgBoss('postgres://user:pass@localhost:5432/mydb');\n\n  boss.on('error', err => console.error(err));\n\n  await boss.start();\n\n  const queue = 'email-queue';\n  await boss.createQueue(queue);\n\n  const jobId = await boss.send(queue, { to: 'user@example.com', subject: 'Hello' });\n  console.log(`Created job ${jobId}`);\n\n  await boss.work(queue, async ([job]) => {\n    console.log(`Processing job ${job.id}: ${JSON.stringify(job.data)}`);\n  });\n\n  console.log('Worker started. Press Ctrl+C to stop.');\n}\n\nmain().catch(err => { console.error(err); process.exit(1); });","lang":"typescript","description":"Shows basic setup: create PgBoss instance, start, create queue, send job, work callback."},"warnings":[{"fix":"Use import { PgBoss } from 'pg-boss' instead of default import.","message":"Version 8+ changed exports from default to named (PgBoss). Old import PgBoss from 'pg-boss' fails.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Upgrade Node.js to >=22.12.0 or use pg-boss@11.x.","message":"Version 12 drops support for Node versions below 22.12.0.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"Always await boss.start() before boss.send() or boss.work().","message":"Calling start() before sending jobs is required; missing start() leads to silent failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace boss.publish() with boss.send().","message":"The method 'publish()' is deprecated in favor of 'send()' since version 6.","severity":"deprecated","affected_versions":">=6.0.0"},{"fix":"Attach an 'error' listener: boss.on('error', console.error).","message":"If you omit 'error' event listener, unhandled errors may crash the process.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Import adapters from 'pg-boss' directly, not from 'pg-boss/adapters'.","message":"Adapter imports (fromKnex, fromKysely, fromPrisma) moved to main package in v8. Importing from subpaths breaks.","severity":"breaking","affected_versions":">=8.0.0"}],"env_vars":null,"search_vec":"'12.18.2':74 '22.12.0':77 'adapt':86 'api':92 'atom':46 'automat':33 'backoff':37 'backpressur':22 'backpressure-compat':21 'base':11,82 'boss':3,6 'cli':70 'commit':47 'compat':23 'creat':50 'cron':25 'databas':54 'dead':27 'deliveri':20 'deploy':63 'differenti':79 'e.g':64 'exact':18 'exactly-onc':17 'exist':53 'exponenti':36 'fan':95 'fan-out':94 'function':68 'guarante':45 'javascript':98 'job':12,51,102 'key':78 'knex':87 'kubernet':65 'kyse':88 'letter':28 'lock':43 'master':62 'migrat':72 'multi':61 'multi-mast':60 'node':76 'node.js':15 'oper':83 'orm':84 'pattern':97 'pg':2,5 'pg-boss':1,4 'poll':24 'postgr':100 'postgresql':10,40,99 'postgresql-bas':9 'prioriti':30 'prisma':89 'provid':16 'pub/sub':91 'queue':13,29,31,101 'replicaset':66 'requir':75 'retri':34 'schedul':26 'serverless':67 'ship':56 'skip':42 'sql':81 'sql-base':80 'support':59 'transact':55,85 'type':58 'typescript':57,103 'use':39 'version':73 'within':52","created_at":"2026-06-05T17:00:16.929612+00:00","updated_at":"2026-06-05T17:00:16.929612+00:00","problems":[{"fix":"Verify PostgreSQL is running and connection string is correct: 'postgres://user:pass@host:port/db'.","cause":"PostgreSQL not running or connection string incorrect.","error":"Error: connect ECONNREFUSED ::1:5432"},{"fix":"Change import to: import { PgBoss } from 'pg-boss'.","cause":"Using default import (PgBoss) instead of named import { PgBoss }.","error":"TypeError: boss.send is not a function"},{"fix":"Run `await boss.start()` or `npx pg-boss migrate` to create required tables.","cause":"pg-boss schema not initialized. start() or migration command missing.","error":"ERROR: relation \"pgboss.job\" does not exist"},{"fix":"Run `npm install pg-boss` and ensure import path is correct.","cause":"pg-boss not installed or wrong import path.","error":"Error: Cannot find module 'pg-boss'"},{"fix":"Use fromKnex(trx) not fromKnex(trx) — call the adapter function with the transaction object.","cause":"Passing import module directly instead of calling adapter factory.","error":"TypeError: adapter must be a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://timgit.github.io/pg-boss","github":"https://github.com/timgit/pg-boss","docs":null,"changelog":null,"pypi":null,"npm":"pg-boss","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}