---
name: nestjs-postgres-redis
description: "Use when building, refactoring, or reviewing a NestJS + PostgreSQL + Redis + BullMQ project (NestJS, Node.js, TypeScript, PostgreSQL, Redis, BullMQ). Enterprise backend architecture guidelines for NestJS modular design, PostgreSQL connection pooling, Redis BullMQ background jobs, and DTO validation."
license: MIT
metadata:
  source: https://stackitfast.com/rules/nestjs-postgres-redis
  version: "2026-09-10"
---

# NestJS + PostgreSQL + Redis + BullMQ — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a NestJS + PostgreSQL + Redis + BullMQ codebase.
- Whenever the project depends on NestJS, Node.js, TypeScript, PostgreSQL, Redis, BullMQ.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (NestJS + PostgreSQL + Redis + BullMQ)

## 1. System Architecture
- **Framework**: NestJS (Modular architecture with Dependency Injection).
- **Database**: PostgreSQL with TypeORM or Prisma ORM.
- **Queue System**: BullMQ backed by Redis for asynchronous jobs and delayed tasks.
- **Validation & Transformation**: `class-validator` and `class-transformer` via global `ValidationPipe`.

## 2. PostgreSQL Connection Management
- When scaling multiple NestJS container replicas, route connections through PgBouncer or configure explicit pool limits:
  ```typescript
  TypeOrmModule.forRootAsync({
    imports: [ConfigModule],
    inject: [ConfigService],
    useFactory: (config: ConfigService) => ({
      type: 'postgres',
      url: config.get<string>('DATABASE_URL'),
      autoLoadEntities: true,
      synchronize: false, // NEVER true in production
      extra: {
        max: 20, // Max pool size per instance
        idleTimeoutMillis: 30000,
        connectionTimeoutMillis: 2000,
      },
    }),
  })
  ```

## 3. Redis & BullMQ Queue Rules (Critical)
- **Redis Eviction Policy**: Set Redis `maxmemory-policy` to `noeviction`. Evicting keys arbitrarily corrupts BullMQ queue states.
- **Worker Process Isolation**: For heavy compute or long-running tasks, instantiate workers in dedicated background worker processes rather than the main API server process.
- **Graceful Shutdown**: Always configure `enableShutdownHooks()` on the NestJS app instance to allow active BullMQ workers to finish jobs before container termination.

## 4. Layer Organization & Dependency Injection
- `src/modules/<resource>/`:
  - `<resource>.controller.ts`: Pure HTTP routing, status codes, and Swagger decorators.
  - `<resource>.service.ts`: Business logic and database operations.
  - `<resource>.processor.ts`: BullMQ `@Processor` handler for background jobs.
  - `dto/`: Strongly typed request/response DTOs with `@IsString()`, `@IsOptional()`, etc.
  - `entities/`: Database schema entities.

## 5. Common Pitfalls to Avoid
- ❌ Enabling `synchronize: true` in production database config (causes data loss).
- ❌ Non-idempotent job handlers: Always check if a background job was already completed before executing side effects.
- ❌ Unhandled Worker Errors: Ensure workers implement event listeners (`@OnWorkerEvent('failed')`) to prevent silent crashes.

## 6. Testing Conventions
- Use Jest (NestJS default) with `@nestjs/testing`'s `Test.createTestingModule` to build isolated module contexts per test suite.
- Mock BullMQ queues in unit tests (`getQueueToken()`); reserve real Redis-backed queue tests for a dedicated integration suite.
- Write e2e tests with `supertest` against a running Nest app instance for every controller endpoint, not just services.
- Assert processor idempotency explicitly: invoke the same job payload twice and assert no duplicate side effects.

## 7. Git Workflow & PR Conventions
- Conventional Commits (`feat:`, `fix:`, `refactor:`) scoped to the module, e.g. `fix(billing): prevent duplicate invoice job processing`.
- TypeORM/Prisma migrations ship in the same PR as the entity change that generated them.
- Require `bun run test`, `bun run test:e2e`, and `tsc --noEmit` green before merge.
- Squash-merge feature branches; never merge with `synchronize: true` left enabled in any committed config.

## Source
Maintained at https://stackitfast.com/rules/nestjs-postgres-redis — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.