Como Corrigir Relações Inválidas Geradas por IA no Prisma

Agentes de IA geram relações de esquema Prisma com relações reversas ausentes, ações referenciais erradas ou tipos de campo incompatíveis que falham no prisma validate e prisma migrate.

O agente escreve um esquema Prisma com relações que parecem corretas, mas falham prisma validate devido a referências reversas ausentes, incompatibilidades de tipo ou configurações ambíguas de múltiplas relações.

O sintoma

Uma relação é declarada em um modelo sem sua contraparte necessária no outro, ou o tipo do campo de chave estrangeira não corresponde ao campo referenciado.

// schema.prisma — WRONG
model User {
  id    String @id @default(cuid())
  posts Post[]
}

model Post {
  id       String @id @default(cuid())
  authorId Int    // Int, but User.id is String — type mismatch
  // Missing: author User @relation(fields: [authorId], references: [id])
}

Executar prisma validate produz:

Error: The relation field `posts` on model `User` is missing an opposite
relation field on the model `Post`.

Por que isso acontece

O agente geralmente escreve um lado de uma relação e esquece de adicionar o outro, especialmente em casos muitos-para-muitos ou autorreferenciais. Ele também copia tipos de campo da memória sem verificar se authorId deve corresponder exatamente ao tipo do id referenciado.

Como identificar

prisma validate ou prisma migrate dev falha com um erro de relação.
Um modelo tem um campo de array (um-para-muitos), mas o modelo referenciado não tem chave estrangeira escalar ou atributo @relation.
Muitos-para-muitos usa tabelas de junção explícitas com tipos incompatíveis.
Modelos autorreferenciais (por exemplo, árvores de categorias) têm apenas um lado do par @relation(name: "...").

Como corrigir

Toda relação deve ter ambos os lados declarados. Os tipos escalares de chave estrangeira devem corresponder exatamente ao tipo do campo referenciado.

// schema.prisma — CORRECT
model User {
  id    String @id @default(cuid())
  posts Post[] // one-to-many: back-reference
}

model Post {
  id       String @id @default(cuid())
  authorId String                       // String, matches User.id
  author   User   @relation(fields: [authorId], references: [id], onDelete: Cascade)
}

Para uma árvore autorreferencial:

model Category {
  id       String     @id @default(cuid())
  parentId String?
  parent   Category?  @relation("CategoryTree", fields: [parentId], references: [id])
  children Category[] @relation("CategoryTree")
}

[ ] Run "prisma validate" before "prisma migrate dev" — fix all errors first
[ ] Every @relation on model A has a matching field on model B
[ ] Foreign key scalar type matches the referenced @id type (String/Int/cuid)
[ ] Self-referential relations use a named @relation("name") on both sides
[ ] Explicit many-to-many join tables declare both foreign keys with onDelete
[ ] onDelete referential action is explicit (Cascade, Restrict, SetNull) — not left to default

Prompt de Correção

This Prisma schema fails prisma validate. Fix every relation error: add the
missing back-reference fields, ensure all foreign key scalar types exactly match
the referenced @id type, give every self-referential relation a unique name on
both sides, and set explicit onDelete actions (Cascade for required relations,
SetNull for optional). Run prisma validate after each change until it passes.

Teste

# Validate schema before attempting migration
npx prisma validate && echo "Schema OK" || echo "FAIL: schema invalid"

# Also check for type mismatches (Int fk -> String id is a common error)
grep -A3 "@relation" prisma/schema.prisma