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 checkreferences/schema-and-migrations.md — Schema design, tipos, relaciones, índices, migracionesreferences/repository-pattern.md — Repositorios como adaptadores de infraestructura (Clean Architecture)references/transactions.md — Transacciones atómicas, SELECT FOR UPDATE, manejo de concurrenciareferences/query-patterns.md — N+1 prevention, include/select, paginación, queries complejasreferences/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
1---2name: prisma-nestjs-patterns3description: Patrones de integración de Prisma ORM con NestJS para aplicaciones de producción. Usar PROACTIVAMENTE cuando se trabaje con esquemas Prisma, migraciones, PrismaService, transacciones atómicas (incluyendo SELECT FOR UPDATE), repositorios como adaptadores de infraestructura en Clean Architecture, queries optimizadas (N+1, includes, paginación), seeds y testing con Prisma Mock. Activar siempre que aparezcan las palabras clave: Prisma, PrismaService, prisma.$transaction, prisma migrate, schema.prisma, PrismaClient, Prisma.validator, include/select, upsert, createMany, o cualquier operación de base de datos con Prisma en un proyecto NestJS.4---56# Prisma ORM + NestJS — Patrones de Producción78Guía completa de integración Prisma con NestJS siguiendo Clean Architecture. Cubre desde la9configuración base hasta transacciones atómicas críticas, repositorios, optimización de queries10y testing.1112## Referencias disponibles1314Lee el archivo correspondiente cuando necesites profundidad en un área específica:1516- `references/setup-and-service.md` — Instalación, PrismaService, módulo global, health check17- `references/schema-and-migrations.md` — Schema design, tipos, relaciones, índices, migraciones18- `references/repository-pattern.md` — Repositorios como adaptadores de infraestructura (Clean Architecture)19- `references/transactions.md` — Transacciones atómicas, SELECT FOR UPDATE, manejo de concurrencia20- `references/query-patterns.md` — N+1 prevention, include/select, paginación, queries complejas21- `references/testing.md` — Testing con jest-mock-extended, prisma-mock, integración con testcontainers2223---2425## Cuándo usar cada referencia2627| Tarea | Referencia |28| ------------------------------------------------ | -------------------------- |29| Configurar Prisma por primera vez en NestJS | `setup-and-service.md` |30| Diseñar o modificar el schema, crear migraciones | `schema-and-migrations.md` |31| Crear repositorios para un módulo de dominio | `repository-pattern.md` |32| Reservas, locks, operaciones concurrentes | `transactions.md` |33| Optimizar queries lentas, eliminar N+1 | `query-patterns.md` |34| Mockear Prisma en tests unitarios/integración | `testing.md` |3536---3738## Reglas críticas (siempre en contexto)3940### 1. PrismaService es global, nunca instanciar PrismaClient directamente4142```typescript43// ❌ Nunca44const prisma = new PrismaClient();4546// ✅ Siempre via inyección de dependencias47constructor(private readonly prisma: PrismaService) {}48```4950### 2. Transacciones atómicas para operaciones de escritura compuestas5152```typescript53// ✅ Patrón correcto para cualquier operación que modifique >1 tabla54await this.prisma.$transaction(async (tx) => {55 const gift = await tx.gift.findUnique({ where: { id: giftId } });56 if (gift.status !== 'AVAILABLE') throw new ConflictException();57 await tx.gift.update({ where: { id: giftId }, data: { status: 'RESERVED' } });58 await tx.reservation.create({ data: { giftId, reservedById: userId } });59});60```6162### 3. Repositorios en la capa de infraestructura, nunca en controllers ni services de dominio6364```typescript65// La interfaz vive en el dominio66export interface ReservationRepository {67 findActiveByGiftId(giftId: string): Promise<Reservation | null>;68 create(data: CreateReservationData): Promise<Reservation>;69}7071// La implementación Prisma vive en infraestructura72@Injectable()73export class PrismaReservationRepository implements ReservationRepository { ... }74```7576### 4. Nunca exponer el PrismaClient fuera del módulo de infraestructura7778Los módulos de dominio y aplicación trabajan contra interfaces, no contra Prisma directamente.7980### 5. Siempre usar `select` o `include` explícito — nunca retornar el modelo completo8182```typescript83// ❌ Retorna passwordHash, campos internos84return this.prisma.user.findUnique({ where: { id } });8586// ✅ Solo los campos necesarios87return this.prisma.user.findUnique({88 where: { id },89 select: { id: true, nombre: true, email: true, createdAt: true }90});91```9293---9495## Fuentes y documentación oficial9697- **Prisma Docs — NestJS Integration**: https://www.prisma.io/docs/guides/other/nestjs98- **Prisma Docs — Transactions**: https://www.prisma.io/docs/orm/prisma-client/queries/transactions99- **Prisma Docs — Interactive Transactions**: https://www.prisma.io/docs/orm/prisma-client/queries/transactions#interactive-transactions100- **Prisma Docs — Select/Include**: https://www.prisma.io/docs/orm/prisma-client/queries/select-fields101- **Prisma Docs — Relation Queries**: https://www.prisma.io/docs/orm/prisma-client/queries/relation-queries102- **Prisma Docs — Migrations**: https://www.prisma.io/docs/orm/prisma-migrate103- **NestJS Docs — Database**: https://docs.nestjs.com/techniques/database104- **Prisma Blog — NestJS Best Practices**: https://www.prisma.io/blog/nestjs-prisma-rest-api-7D056s1BmOL0105- **jest-mock-extended**: https://github.com/marchaos/jest-mock-extended
davidcastagnetoa