Prisma ORM + NestJS — Patrones de Producción

Referencias disponibles

• 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

setup-and-service.md

schema-and-migrations.md

repository-pattern.md

transactions.md

query-patterns.md

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

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