# `@wavezync/nestjs-pgboss`
Use pg-boss in your Nest.js app!
## 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+.
```bash
npm install pg-boss @wavezync/nestjs-pgboss
```
```bash
yarn add pg-boss @wavezync/nestjs-pgboss
```
```bash
pnpm add pg-boss @wavezync/nestjs-pgboss
```
## Usage
### Setup
To begin using `@wavezync/nestjs-pgboss`, initialize the root module:
```ts
import { PGBossModule } from "@wavezync/nestjs-pgboss";
// app.module.ts
@Module({
imports: [
PgBossModule.forRootAsync({
imports: [ConfigModule],
useFactory: async (configService: ConfigService) => ({
connectionString: configService.get('DATABASE_URL'),
}),
inject: [ConfigService],
}),
],
})
export class AppModule {}
```
#### Schedule a job using `PgBossService`
```ts
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
```ts
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[]) {
this.logger.log(`Processing ${jobs.length} job(s)`);
}
}
```
#### Handle cron jobs using the `@CronJob` decorator
```ts
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:
```ts
@Job('my-job', { batchSize: 5 }, { retryLimit: 5, retryDelay: 30 })
async handleMyJob(jobs: JobWithMetadata[]) { ... }
@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
```bash
# unit tests
$ npm run test
```
## License
`@wavezync/nestjs-pgboss` is [MIT licensed](LICENSE)