Padrões Prisma

Padrões de produção e armadilhas não óbvias para Prisma ORM em backends TypeScript.

Verifique sua versão antes de aplicar os padrões. A superfície da API do Prisma evoluiu entre as principais versões:

npx prisma --version

Diferenças notáveis na API entre as versões:

• relationJoins pode carregar relações via JOIN em vez de consultas separadas, mas pode causar explosão de linhas em relações 1:N grandes ou include profundas — compare ambos os métodos
• O modificador de campo omit e a API prisma.$extends Client Extensions foram adicionados
• Instalações mais recentes: o pacote pode ser nomeado prisma em vez de @prisma/client; PrismaClient pode exigir um adaptador de driver (por exemplo, @prisma/adapter-pg); datasource.url pode estar em prisma.config.ts em vez de schema.prisma
• Comandos CLI (migrate dev, migrate deploy, generate) não foram alterados entre as versões

Quando Ativar

• Projetando ou modificando modelos e relações do esquema Prisma
• Escrevendo consultas, transações ou lógica de paginação
• Usando updateMany, deleteMany ou qualquer operação em massa
• Executando ou planejando migrações de banco de dados
• Implantando em ambientes serverless (Vercel, Lambda, Cloudflare Workers)
• Implementando soft delete ou filtragem de linhas multi-tenant

Conceitos Principais

Estratégia de ID

Padrões do Schema

model User {
  id        String    @id @default(cuid())
  email     String    @unique  // @unique already creates an index — no @@index needed
  name      String
  role      Role      @default(USER)
  posts     Post[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime?

  @@index([createdAt])
  @@index([deletedAt, createdAt]) // composite for soft-delete + sort queries
}

• Adicione @@index em cada chave estrangeira e coluna usada em WHERE ou ORDER BY.
• Declare deletedAt DateTime? antecipadamente quando o soft delete for um requisito previsível — adicioná-lo mais tarde requer uma migração em uma tabela ativa.
• updatedAt @updatedAt é definido automaticamente pelo Prisma apenas em update e upsert (veja Anti-Padrões para a armadilha de atualização em massa).

include vs select

// include — all columns + relation
const user = await prisma.user.findUnique({
  where: { id },
  include: { posts: { select: { id: true, title: true } } },
});

// select — explicit allowlist
const user = await prisma.user.findUnique({
  where: { id },
  select: { id: true, email: true, name: true },
});

Nunca retorne entidades Prisma brutas de respostas de API — mapeie para DTOs de resposta para controlar os campos expostos:

// BAD: leaks passwordHash, deletedAt, internal fields
return await prisma.user.findUniqueOrThrow({ where: { id } });

// GOOD: explicit DTO mapping
const user = await prisma.user.findUniqueOrThrow({ where: { id } });
return { id: user.id, name: user.name, email: user.email };

Seleção de Forma de Transação

// Array form — batched in one round trip
const [user, post] = await prisma.$transaction([
  prisma.user.update({ where: { id }, data: { name } }),
  prisma.post.create({ data: { title, authorId: id } }),
]);

// Interactive form — use tx client only, never the outer prisma client
const post = await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUniqueOrThrow({ where: { id } });
  if (user.role !== 'ADMIN') throw new Error('Forbidden');
  return tx.post.create({ data: { title, authorId: user.id } });
});

Singleton PrismaClient

…