VENNStart
Guide

Scheduled jobs in Node.js with pg-boss and NestJS

Publishing posts on time from a Postgres job queue: pg-boss in its own NestJS worker, queue policies, retries, jobs that run twice, and deploys.

Lê Anh Tuấn5 min read

My side project queues people's posts for a scheduled time and publishes them to each selected platform. The scheduling runs on pg-boss (^12.34.0), a Postgres job queue, in its own NestJS worker inside a pnpm monorepo (NestJS API, a few Next.js apps, Prisma 7). The queue bugs here, including one real duplicate post, came from queue configuration and how jobs claim rows.

Postgres instead of adding Redis

BullMQ on Redis is the default in Node, and it's a good library. On a team of one, though, every extra service is something to run, back up and pay for, and on free tiers it also goes to sleep.

pg-boss keeps jobs in a pgboss schema inside the database I already run. Workers fetch with SELECT ... FOR UPDATE SKIP LOCKED, which keeps two workers off the same job row. When something looks off, I query it with plain SQL.

In exchange, the publish worker polls the API's own Postgres every 2 seconds, and a runaway backlog grows in that same database.

The worker is a second entry point into the same code

main.ts builds the HTTP app. worker.ts builds an application context with no HTTP server:

// worker.ts
async function bootstrap(): Promise<void> {
  const app = await NestFactory.createApplicationContext(WorkerModule)
  app.enableShutdownHooks() // so SIGTERM reaches onModuleDestroy and pg-boss can stop
}
void bootstrap()

// worker.module.ts
@Module({
  imports: [DatabaseModule, SchedulerModule, PlatformsModule, PublisherModule /* ... */],
  // Only here: its onModuleInit registers the pg-boss handlers,
  // so importing this module twice in one process registers them twice.
  providers: [PublishWorker],
})
export class WorkerModule {}

PublishWorker.onModuleInit registers the handlers and cron schedules, then re-arms anything that should already be queued. Video AI jobs wait minutes on a provider and run separately in ai-worker.ts.

Render's free plan has no background workers, so a flag called ENABLE_INLINE_WORKER mounts WorkerModule inside the API process. That service sleeps after 15 minutes without requests, leaving jobs in Postgres that nobody picks up, so it needs an uptime service hitting /health every 10 minutes.

singletonKey only dedupes on a stately queue

The publish queue is created with roughly this:

// queue.options.ts (names simplified)
import type { Queue } from 'pg-boss'

export const QUEUE = { publish: 'app-publish', deadLetter: 'app-dead-letter' } as const

export const DEAD_LETTER_OPTIONS: Omit<Queue, 'name'> = {
  retryLimit: 0,
  deleteAfterSeconds: 60 * 60 * 24 * 14, // kept two weeks, for reading
}

export const PUBLISH_OPTIONS: Omit<Queue, 'name'> = {
  policy: 'stately',      // makes singletonKey a real constraint
  retryLimit: 2,          // only covers a worker that died mid-job
  retryDelay: 30,
  retryBackoff: true,
  expireInSeconds: 3_600, // was 300, see below
  deleteAfterSeconds: 60 * 60 * 24 * 7,
  deadLetter: QUEUE.deadLetter, // must exist before this queue is created
}

pg-boss's default policy is standard, where a singletonKey doesn't block a second job. Publish jobs went out with singletonKey: targetId, while the boot reconcile re-sent a job for every pending target, adding a copy per target on each restart. When the fix went in there were 71,015 queued publish jobs for 1,217 targets, one of them 108 jobs deep.

stately allows one queued and one active job per key. singleton still allows unlimited queued jobs. exclusive allows one job queued or active, which would break the handler arming its own retry while its job is still active.

createQueue leaves an existing queue alone, and updateQueue can't change policy. At boot, any queue whose stored policy differs from the code gets deleted and recreated:

// Creation order matters: the dead-letter queue first, because publish names it.
for (const key of Object.keys(QUEUE_OPTIONS) as Array<keyof typeof QUEUE>) {
  await boss.createQueue(QUEUE[key], QUEUE_OPTIONS[key])
}

for (const key of Object.keys(QUEUE_OPTIONS) as Array<keyof typeof QUEUE>) {
  const wanted = QUEUE_OPTIONS[key].policy
  const existing = await boss.getQueue(QUEUE[key])
  if (!wanted || !existing || existing.policy === wanted) continue

  // Drops the queued jobs on purpose. Publish jobs are derived from PostTarget rows,
  // and reconcile() re-arms one per pending target right after this.
  await boss.deleteQueue(QUEUE[key])
  await boss.createQueue(QUEUE[key], QUEUE_OPTIONS[key])
  logger.warn(`Recreated ${QUEUE[key]}: ${existing.policy} -> ${wanted}`)
}

QUEUE_OPTIONS is a Record<keyof typeof QUEUE, ...> because when I added the watchdog queue, boot still had three hand-written createQueue calls and I never wrote the fourth. My old dev database still had that queue. On a fresh one, the watchdog never ran.

One owner for retries, and a timeout longer than the work

The publish handler catches its own errors and schedules the next attempt (1, 2, 4 minutes, capped at 15), because it knows which failures deserve a retry. A revoked token doesn't. pg-boss's retryLimit only matters when the worker crashes or the job expires. If both sides retry, attempts multiply.

expireInSeconds used to be 300, and the publish queue has no heartbeat. A 500 MB video still uploading to TikTok timed out after five minutes and was retried 30 seconds later, and a second worker published the same target while the first was still uploading. It's an hour now. The publish queue doesn't use pg-boss 12's heartbeatSeconds yet, and a truly stuck publish is the watchdog's problem.

Jobs can arrive twice, so claim the row first

Crash retries, the boot reconcile, "Share now" and edits can each deliver the same publish twice. The handler checks the row before publishing:

// Every legitimate path sets PENDING before it sends a job.
// Anything else arriving here is a redelivery.
if (target.status !== 'PENDING' && target.status !== 'PUBLISHING') return

if (target.status === 'PUBLISHING') {
  // A running attempt bumps updatedAt every minute.
  const lastSign = Math.max(target.lastAttemptAt?.getTime() ?? 0, target.updatedAt.getTime())
  if (Date.now() - lastSign < STALE_PUBLISH_MS) return // someone is on it
  if (!target.providerJobId) return beginOutcomeCheck(target) // ask the platform first
}

// Compare-and-set on exactly what was read.
const claimed = await prisma.postTarget.updateMany({
  where: { id: target.id, status: target.status, updatedAt: target.updatedAt },
  data: { status: 'PUBLISHING', attempts: target.attempts + 1, lastAttemptAt: new Date() },
})
if (claimed.count === 0) return // another job got there first

If two jobs read the same row, only one updateMany matches. A target that has shown no sign of life in PUBLISHING for STALE_PUBLISH_MS (10 minutes) is taken over only when the platform gave back a job it can poll (TikTok's publish_id). Otherwise the handler first schedules an outcome check against the platform.

My first conditional claim also accepted FAILED and SKIPPED. The watchdog failed a target as "outcome unknown", pg-boss redelivered the old job, and the handler published a second copy. Now only PENDING or a stale PUBLISHING can be claimed. If scheduledAt is more than 5 seconds away, the handler re-arms the job instead of publishing.

startAfter for posts, cron for sweeps

Each target is one job with startAfter in seconds. pg-boss reads an ISO string without a zone as UTC.

The watchdog, metrics and renewal reminders use boss.schedule() with cron, which needs at least one instance running. In 12.34 the default missed: 'skip' drops an occurrence that came due while nothing was running.

Cron is evaluated in UTC unless you pass tz. The reminder cron 0 2 * * * has a comment calling 2 a.m. the time nobody is waiting, and it runs at 9 a.m. in Ho Chi Minh City. I wrote about why I moved a cron job out of an Express API, and the reasoning is the same here.

Deploys, restarts and what I watch

boss.stop() waits for active handlers, then fails whatever is still running. Its default wait is 30 seconds, and Docker's default stop grace period is 10, so the container would be killed before anything got failed. The worker passes timeout: 8_000 instead. By the code, the retry sees a recent PUBLISHING and returns, and the watchdog later starts an outcome check against the platform. I haven't verified that path.

The worker container also starts through sh -c 'pnpm start:worker', and I'm not sure SIGTERM reaches Node at all.

Neon's free compute suspends after five idle minutes. The boot reconcile retries at 0, 1.5 and 4 seconds and then throws, because a malformed DATABASE_URL or a missing schema should still fail the deploy.

Plain SQL is the most useful view of the queue:

SELECT name, state, count(*)
FROM pgboss.job
GROUP BY name, state
ORDER BY name, state;

I check for created jobs piling up past their start time, long-running active jobs, dead-letter rows, and queue names nobody handles anymore. The product got renamed twice, and both old queue names left jobs behind that never complete.

  • NestJS
  • pg-boss
  • PostgreSQL
  • Node.js
  • Background jobs
  • Backend

I'm Tuấn (Venn), a web developer in Ho Chi Minh City. I mostly build Next.js sites and web apps, and I take freelance work.

Work with me

More posts

  1. 01Guide4 min read

    Deploying Next.js and NestJS to AWS EC2 with Docker Compose

    How I deploy a pnpm monorepo to one EC2 box. Images get built in GitHub Actions and Docker Compose pulls them from GHCR. The server has no code.

  2. 02Guide4 min read

    How I store OAuth tokens for social media APIs in NestJS

    OAuth for Facebook, TikTok and YouTube in a NestJS API. State and PKCE, encrypted tokens, refreshing before each publish, and when to ask for a reconnect.

  3. 03vennee.dev3 min read

    llms.txt on my Next.js site, and now Lighthouse grades it

    vennee.dev has a hand-written llms.txt and an llms-full.txt built from the blog. Notes on the spec, .txt routes in Next.js, and Lighthouse 13's new audit.