pg-boss in production: footguns we hit and how to avoid them

1. singletonKey without singletonSeconds is a no-op on standard queues

pg-boss 12.x · default queue policy · silent failure mode

import PgBoss from 'pg-boss'

const boss = new PgBoss({ connectionString: process.env.DATABASE_URL! })
await boss.start()
try {
  await boss.createQueue('demo') // idempotent in v10+

  const ids = await Promise.all(
    Array.from({ length: 6 }, () =>
      boss.send('demo', { x: 1 }, { singletonKey: 'k' }),
    ),
  )
  console.log(ids.filter(Boolean).length) // -> 6, not 1
} finally {
  await boss.stop()
}

2. boss.send() returns null on dedup, silently

pg-boss 12.x · documented, easy to discard

import PgBoss from 'pg-boss'

const boss = new PgBoss({ connectionString: process.env.DATABASE_URL! })
await boss.start()
try {
  await boss.createQueue('demo')

  const a = await boss.send('demo', { x: 1 },
    { singletonKey: 'k', singletonSeconds: 60 })
  console.log(a) // -> '01H...' (uuid)

  const b = await boss.send('demo', { x: 1 },
    { singletonKey: 'k', singletonSeconds: 60 })
  console.log(b) // -> null
} finally {
  await boss.stop()
}

3. boss.schedule() upserts on (name, key) — schedules silently overwrite

pg-boss 12.x · documented, easy to misuse

import PgBoss from 'pg-boss'

const boss = new PgBoss({ connectionString: process.env.DATABASE_URL! })
await boss.start()
try {
  await boss.createQueue('maintenance')

  await boss.schedule('maintenance', '*/2 * * * *', { task: 'expiry-sweep' })
  await boss.schedule('maintenance', '*/5 * * * *', { task: 'audit-checkpoint' })
  await boss.schedule('maintenance', '0 * * * *',   { task: 'reputation-roll' })

  // Inspect with: SELECT name, key, cron, data FROM pgboss.schedule;
  //
  // Expected: three rows.
  // Actual:   one row, name='maintenance', key='', cron='0 * * * *',
  //           data={task:'reputation-roll'}.
} finally {
  await boss.stop()
}

SELECT name, key, count(*)
FROM pgboss.schedule
GROUP BY 1, 2
HAVING count(*) > 1;

If that returns rows, you have collisions.

4. Schema drift across pg-boss majors

pg-boss v10, v11, v12 · silent breakage in raw SQL

import { Pool } from 'pg'

const pool = new Pool({ connectionString: process.env.DATABASE_URL! })

// A "find old completed jobs" query that worked on pg-boss 10.x:
const completed = await pool.query(`
  SELECT id, completed_on FROM pgboss.archive
  WHERE name = $1 AND completed_on > now() - interval '7 days'
`, ['demo'])

// On pg-boss <= 10.x: returns rows.
// On pg-boss 11.x+:   throws 'relation "pgboss.archive" does not exist'
// — but only when this query actually runs, which for a weekly sweep
// can be days after the upgrade if the sweep is in a try/catch that
// logs-and-continues.

await pool.end()

const REQUIRED = ['name', 'state', 'singleton_key'] as const
const { rows } = await pool.query<{ column_name: string }>(`
  SELECT column_name FROM information_schema.columns
  WHERE table_schema = 'pgboss' AND table_name = 'job'
`)
const present = new Set(rows.map(r => r.column_name))
const missing = REQUIRED.filter(c => !present.has(c))
if (missing.length > 0) {
  throw new Error(`pgboss.job missing columns: ${missing.join(', ')}`)
}

The same sentinel pattern works in your migrations gate if you maintain ops dashboards.

Fixed upstream: issue #535

pg-boss 11.0.8 (2025-10-10) · backport in 10.4.0 (2025-11-19)

-- pg-boss v11+ — completed jobs live in pgboss.job until
-- deleteAfterSeconds elapses (the archive table was removed in v11).
SELECT singleton_key, COUNT(*), MIN(completed_on), MAX(completed_on)
FROM pgboss.job
WHERE state = 'completed'
  AND singleton_key IS NOT NULL
  AND completed_on > now() - interval '7 days'
GROUP BY singleton_key
HAVING COUNT(*) > 1
   AND MAX(completed_on) - MIN(completed_on) < interval '5 seconds'
ORDER BY 2 DESC LIMIT 20;

-- pg-boss v10.x — query pgboss.archive instead (or in addition).

Credit goes upstream. The fix landed in 11.0.8 via the maintainer (timgit) and was backported to the v10 line in PR #640 by @nrempel, released as 10.4.0. We just had to upgrade.

Honest about scope

Sources & further reading

• pg-boss on GitHub (MIT, maintained by timgit)
• pg-boss issue #535 — worker stops with singleton key in retry + created and batch > 1; fixed in 11.0.8 / 10.4.0
• pg-boss issue #548 — replace-vs-discard semantics, open as of 2026-05-03
• pg-boss issue #81 — historical singleton context (closed 2018)
• pg-boss release notes — v10, v11, v12 breaking changes
• PostgreSQL information_schema.columns — reference for the schema sentinel pattern
• Crunchy Data: Postgres information_schema, the other system catalog — background on information_schema vs pg_catalog for the startup-sentinel pattern
• pg-boss v10.0.0 release notes — snake_case column rename, queue policies, partitioned tables
• pg-boss v11.0.0 release notes — archive table removed, retention semantics changed
• Brandur Leach: Postgres as a queue — canonical piece on the broader pattern pg-boss implements
• Brandur Leach: Implementing Stripe-like idempotency keys — relevant to the “treat dedup signals as required-to-handle” pattern in Footgun 2

Related