Přeskočit na obsah

Prisma include na přejmenovanou relaci — typ „never", build projde, runtime 500

import { Aside } from ‘@astrojs/starlight/components’;

Jedna konkrétní obrazovka přestane fungovat, zbytek aplikace jede:

  • endpoint detailu vrací HTTP 500
  • modal / detailová stránka se neotevře nebo zůstane v načítání
  • v logu opakovaně Unknown field \payment` for include statement on model `BankTransaction`. Available options are marked with ?.`
  • tsc --noEmit i produkční build projdou bez jediné chyby
  • CI je zelené, deploy proběhne, problém se ukáže až u uživatelů

Zákeřné na tom je, že chyba nevznikne v okamžiku přejmenování, ale až když se poprvé vygeneruje nový Prisma klient — mezi commitem a projevem tak může být i několik nasazení.

Ve schématu se relace změnila z 1:1 na 1:N a s ní i její název:

model BankTransaction {
// dřív:
// payment Payment?
// nově:
payments Payment[]
}

Volající kód ale zůstal na starém názvu:

const DETAIL_INCLUDE = {
bankAccount: { select: { id: true, name: true } },
payment: { // ← relace už se jmenuje payments
include: { invoice: { select: { id: true, number: true } } },
},
} as const;
const tx = await prisma.bankTransaction.findUnique({
where: { id },
include: DETAIL_INCLUDE,
});

Proč to typecheck nechytí: Prisma neoznačí neznámý klíč v include jako chybu — odvodí pro něj typ never. Výsledek se pak tváří jako { ..., payment: never }, což je přiřaditelné kamkoli a nikde to nezaskřípe. as const situaci ještě zhorší: objekt se předává jako hodnota, takže se neporovnává proti XxxInclude v místě zápisu. Kontrola typu tedy potvrdí kód, který databáze odmítne.

Validace probíhá až za běhu v query engine — proto 500 místo červeného buildu.

Srovnat include se schématem a výsledek převést do tvaru, který očekává API kontrakt a frontend:

const DETAIL_INCLUDE = {
bankAccount: { select: { id: true, name: true } },
payments: { // ← skutečný název relace
include: { invoice: { select: { id: true, number: true } } },
},
} as const;
/**
* DB vrací seznam, API kontrakt drží JEDNU účinnou položku.
* Signatura vyžaduje `payments` — další přejmenování shodí build, ne produkci.
*/
function toDetailShape<P, T extends { payments: P[] }>(
row: T
): Omit<T, "payments"> & { payment: P | null } {
const { payments, ...rest } = row;
return { ...rest, payment: payments[0] ?? null };
}
const row = await prisma.bankTransaction.findUnique({ where: { id }, include: DETAIL_INCLUDE });
if (!row) return notFound();
const tx = toDetailShape(row); // frontend dál čte tx.payment

Ten helper je tu to podstatné: přesune chybu z runtime do buildu. S ním tsc na starém názvu spadne (Argument of type '{ ...; payment: never; }' is not assignable to parameter of type '{ payments: unknown[]; }').

Přejmenování relace se typicky projeví jen na některých místech, takže hledej systematicky:

Terminál
# 1) vypiš relace modelu ze schématu
awk '/^model BankTransaction/,/^}/' prisma/schema.prisma
# 2) najdi v kódu starý název v include/select (pozor na false positives typu paymentId)
grep -rn 'payment:' src/ | grep -vE 'payments:|paymentId|paymentMethod|paymentTerms'
# 3) posbírej runtime důkazy z logu — tohle je jediné místo, kde se to projeví
grep -c 'Unknown field .* for include statement' /path/to/app-error.log

Bod 3 je zároveň dobrý smoke test po každé migraci schématu: pokud počet po nasazení roste, něco jsi minul.

  • Zelený build není důkaz, že dotazy sedí se schématem. U Prisma platí, že typová kontrola pokrývá tvar výsledku, ne existenci polí v include.
  • Přejmenování relace je breaking change pro celý repozitář, ne lokální úprava schématu. Patří k němu grep a proklikání dotčených obrazovek.
  • Když část kódu na migraci zareaguje a část ne, vzniká nejhorší varianta: většina appky funguje a rozbitá je jedna obrazovka, které si nikdo nevšimne dny.
  • Pomáhá držet stabilní API kontrakt (ven jde payment) nezávisle na tvaru v DB (payments) — frontend pak migraci schématu vůbec nepocítí.
Přidal aiarchitekt.cz · 10. 9. 2026 2:00
Provozuje aiarchitekt.cz