@wavezync/nestjs-pgboss

Features

• Decorator-based job handling — Use @Job() and @CronJob() decorators to define workers directly on your service methods
• Cron scheduling — Schedule recurring jobs with cron expressions and timezone support
• Automatic queue creation — Queues are created automatically before any job operation
• Parallel processing — Configure teamSize and teamConcurrency for parallel job workers
• Connection retry logic — Built-in retry with configurable retryLimit and retryDelay for resilient startup
• Graceful shutdown — PgBoss is automatically stopped when the NestJS application shuts down
• Full pg-boss access — Access the underlying PgBoss instance directly for advanced use cases

Installation

Version 7 requires NestJS 12 and Node.js 22.12+.

npm install pg-boss @wavezync/nestjs-pgboss

yarn add pg-boss @wavezync/nestjs-pgboss

pnpm add pg-boss @wavezync/nestjs-pgboss

Usage

Setup

To begin using @wavezync/nestjs-pgboss, initialize the root module:

import { PGBossModule } from "@wavezync/nestjs-pgboss";

// app.module.ts
@Module({
  imports: [
    PgBossModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        connectionString: configService.get<string>('DATABASE_URL'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Schedule a job using PgBossService

import { Injectable } from '@nestjs/common';
import { PgBossService } from '@wavezync/nestjs-pgboss';

@Injectable()
export class JobSchedulerService {
  constructor(private readonly pgBossService: PgBossService) {}

  async scheduleJob() {
    await this.pgBossService.scheduleJob('my-job', { key: 'value' });
  }
}

Access boss Directly

You can access the PgBoss instance directly via pgBossService.boss

Handle jobs using the @Job decorator

import { Injectable, Logger } from '@nestjs/common';
import { Job } from '@wavezync/nestjs-pgboss';
import { JobWithMetadata } from 'pg-boss';

interface MyJobData {
  id: number;
  name: string;
}

@Injectable()
export class MyJobHandler {
  private readonly logger = new Logger(MyJobHandler.name);

  @Job('my-job')
  async handleMyJob(jobs: JobWithMetadata<MyJobData>[]) {
    this.logger.log(`Processing ${jobs.length} job(s)`);
  }
}

Handle cron jobs using the @CronJob decorator

import { Injectable, Logger } from '@nestjs/common';
import { PgBossService, CronJob } from '@wavezync/nestjs-pgboss';

@Injectable()
export class MyCronJobService {
  private readonly logger = new Logger(MyCronJobService.name);

  @CronJob('my-cron-job', '0 * * * *', { priority: 1 })
  async handleCron() {
    this.logger.log('Executing cron job: my-cron-job');
  }
}

Configure retries and other queue options

Retry policy is a queue-level setting in pg-boss, so it goes in the optional queueOptions argument (applied via createQueue). Queue-level settings are inherited by every job in the queue unless overridden when the job is sent:

@Job('my-job', { batchSize: 5 }, { retryLimit: 5, retryDelay: 30 })
async handleMyJob(jobs: JobWithMetadata<MyJobData>[]) { ... }

@CronJob('my-cron-job', '0 * * * *', { retryLimit: 3 })
async handleCron() { ... }

Supported queue options include retryLimit (default 2), retryDelay, retryBackoff, expireInSeconds, retentionSeconds, deleteAfterSeconds and deadLetter. Options passed at send time (scheduleJob, scheduleCronJob, or the @CronJob schedule options, which already include all queue options) take precedence over these queue defaults.

Test

# unit tests
$ npm run test

License

@wavezync/nestjs-pgboss is MIT licensed