Prisma ORM + NestJS — Patrones de Producción

Guía completa de integración Prisma con NestJS siguiendo Clean Architecture. Cubre desde la configuración base hasta transacciones atómicas críticas, repositorios, optimización de queries y testing.

Referencias disponibles

Lee el archivo correspondiente cuando necesites profundidad en un área específica:

references/setup-and-service.md — Instalación, PrismaService, módulo global, health check
references/schema-and-migrations.md — Schema design, tipos, relaciones, índices, migraciones
references/repository-pattern.md — Repositorios como adaptadores de infraestructura (Clean Architecture)
references/transactions.md — Transacciones atómicas, SELECT FOR UPDATE, manejo de concurrencia
references/query-patterns.md — N+1 prevention, include/select, paginación, queries complejas
references/testing.md — Testing con jest-mock-extended, prisma-mock, integración con testcontainers

Cuándo usar cada referencia

Tarea	Referencia
Configurar Prisma por primera vez en NestJS	`setup-and-service.md`
Diseñar o modificar el schema, crear migraciones	`schema-and-migrations.md`
Crear repositorios para un módulo de dominio	`repository-pattern.md`
Reservas, locks, operaciones concurrentes	`transactions.md`
Optimizar queries lentas, eliminar N+1	`query-patterns.md`
Mockear Prisma en tests unitarios/integración	`testing.md`

Reglas críticas (siempre en contexto)

1. PrismaService es global, nunca instanciar PrismaClient directamente

// ❌ Nunca
const prisma = new PrismaClient();

// ✅ Siempre via inyección de dependencias
constructor(private readonly prisma: PrismaService) {}

2. Transacciones atómicas para operaciones de escritura compuestas

// ✅ Patrón correcto para cualquier operación que modifique >1 tabla
await this.prisma.$transaction(async (tx) => {
  const gift = await tx.gift.findUnique({ where: { id: giftId } });
  if (gift.status !== 'AVAILABLE') throw new ConflictException();
  await tx.gift.update({ where: { id: giftId }, data: { status: 'RESERVED' } });
  await tx.reservation.create({ data: { giftId, reservedById: userId } });
});

3. Repositorios en la capa de infraestructura, nunca en controllers ni services de dominio

// La interfaz vive en el dominio
export interface ReservationRepository {
  findActiveByGiftId(giftId: string): Promise<Reservation | null>;
  create(data: CreateReservationData): Promise<Reservation>;
}

// La implementación Prisma vive en infraestructura
@Injectable()
export class PrismaReservationRepository implements ReservationRepository { ... }

4. Nunca exponer el PrismaClient fuera del módulo de infraestructura

Los módulos de dominio y aplicación trabajan contra interfaces, no contra Prisma directamente.

5. Siempre usar `select` o `include` explícito — nunca retornar el modelo completo

// ❌ Retorna passwordHash, campos internos
return this.prisma.user.findUnique({ where: { id } });

// ✅ Solo los campos necesarios
return this.prisma.user.findUnique({
  where: { id },
  select: { id: true, nombre: true, email: true, createdAt: true }
});

Fuentes y documentación oficial

Prisma Docs — NestJS Integration: https://www.prisma.io/docs/guides/other/nestjs
Prisma Docs — Transactions: https://www.prisma.io/docs/orm/prisma-client/queries/transactions
Prisma Docs — Interactive Transactions: https://www.prisma.io/docs/orm/prisma-client/queries/transactions#interactive-transactions
Prisma Docs — Select/Include: https://www.prisma.io/docs/orm/prisma-client/queries/select-fields
Prisma Docs — Relation Queries: https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries
Prisma Docs — Migrations: https://www.prisma.io/docs/orm/prisma-migrate
NestJS Docs — Database: https://docs.nestjs.com/techniques/database
Prisma Blog — NestJS Best Practices: https://www.prisma.io/blog/nestjs-prisma-rest-api-7D056s1BmOL0
jest-mock-extended: https://github.com/marchaos/jest-mock-extended

prisma-nestjs-patterns