prisma-patterns

Modèles Prisma

Modèles de production et pièges non évidents pour Prisma ORM dans les backends TypeScript.

Vérifiez votre version avant d'appliquer les modèles. La surface d'API de Prisma a évolué à travers les versions majeures :

npx prisma --version

Différences notables selon les versions :

• relationJoins peut charger les relations via JOIN plutôt que des requêtes séparées, mais peut entraîner une explosion de lignes sur les grandes relations 1:N ou les include profonds — testez les deux approches
• Le modificateur de champ omit et l'API d'extensions client prisma.$extends ont été ajoutés
• Nouvelles installations : le package peut s'appeler prisma au lieu de @prisma/client ; PrismaClient peut nécessiter un adaptateur pilote (par ex. @prisma/adapter-pg) ; datasource.url peut se trouver dans prisma.config.ts au lieu de schema.prisma
• Les commandes CLI (migrate dev, migrate deploy, generate) sont inchangées d'une version à l'autre

Quand Activer

• Concevoir ou modifier des modèles et relations de schéma Prisma
• Écrire des requêtes, transactions ou logique de pagination
• Utiliser updateMany, deleteMany ou toute opération en masse
• Exécuter ou planifier des migrations de base de données
• Déployer dans des environnements serverless (Vercel, Lambda, Cloudflare Workers)
• Implémenter la suppression en douceur ou le filtrage multi-tenant par ligne

Concepts Fondamentaux

Stratégie d'ID

Stratégie	Quand l'utiliser	Quand l'éviter
@default(cuid())	Choix par défaut — sûr pour les URL, triable, sans collision	ID séquentiels nécessaires pour des systèmes externes
@default(uuid())	Interopérabilité avec des systèmes non-Prisma requise	Tables à forte écriture (les UUID aléatoires fragmentent les index B-tree)
@default(autoincrement())	Tables de jointure internes, journaux d'audit	ID exposés publiquement (révèle le nombre d'enregistrements)

Valeurs par Défaut du Schéma

model User {
  id        String    @id @default(cuid())
  email     String    @unique  // @unique crée déjà un index — pas besoin de @@index
  name      String
  role      Role      @default(USER)
  posts     Post[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
  deletedAt DateTime?

  @@index([createdAt])
  @@index([deletedAt, createdAt]) // composite pour suppression en douceur + tri
}

• Ajoutez @@index sur chaque clé étrangère et colonne utilisée dans WHERE ou ORDER BY.
• Déclarez deletedAt DateTime? dès le départ lorsque la suppression en douceur est un besoin prévisible — l'ajouter plus tard nécessite une migration sur une table en production.
• updatedAt @updatedAt est défini automatiquement par Prisma sur update et upsert uniquement (voir Anti-modèles pour le piège des mises à jour en masse).

include vs select

Caractéristique	include	select
Retourne	Tous les champs scalaires + relations spécifiées	Uniquement les champs spécifiés
Quand l'utiliser	Vous avez besoin de la plupart des champs plus une relation	Chemins chauds, grandes tables, éviter le surchargement
Performances	Peut surcharger sur les tables larges	Charge utile minimale, plus rapide sur les grands ensembles de données
Note Prisma 5	Utilise JOIN par défaut (relationJoins)	Identique

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

// select — liste d'autorisation explicite
const user = await prisma.user.findUnique({
  where: { id },
  select: { id: true, email: true, name: true },
});

Ne retournez jamais d'entités Prisma brutes depuis les réponses API — mappez vers des DTO de réponse pour contrôler les champs exposés :

// MAUVAIS : fuit passwordHash, deletedAt, champs internes
return await prisma.user.findUniqueOrThrow({ where: { id } });

// BON : mappage DTO explicite
const user = await prisma.user.findUniqueOrThrow({ where: { id } });
return { id: user.id, name: user.name, email: user.email };

Sélection de la Forme de Transaction

Situation	Utiliser
Opérations indépendantes, sans interdépendance	Forme tableau
L'étape suivante dépend du résultat précédent	Forme interactive
Appels externes (email, HTTP) impliqués	En dehors de la transaction complètement

// Forme tableau — regroupées en un seul aller-retour
const [user, post] = await prisma.$transaction([
  prisma.user.update({ where: { id }, data: { name } }),
  prisma.post.create({ data: { title, authorId: id } }),
]);

// Forme interactive — utiliser uniquement le client tx, jamais le client prisma externe
const post = await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUniqueOrThrow({ where: { id } });
  if (user.role !== 'ADMIN') throw new Error('Accès interdit');
  return tx.post.create({ data: { title, authorId: user.id } });
});

Singleton PrismaClient

Chaque instance PrismaClient ouvre son propre pool de connexions. Instanciez une seule fois.

// lib/prisma.ts

// Option A — initialisation basée sur adaptateur (requise par les nouvelles installations Prisma)
import { PrismaClient } from '@prisma/client'; // ou le chemin du client généré pour votre configuration
import { PrismaPg } from '@prisma/adapter-pg';

function createPrismaClient() {
  const adapter = new PrismaPg({
    connectionString: process.env.DATABASE_URL!,
  });
  return new PrismaClient({
    adapter,
    log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
  });
}

const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };

export const prisma = globalForPrisma.prisma ?? createPrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

// Option B — initialisation directe (anciennes installations, pas d'adaptateur nécessaire)
// import { PrismaClient } from '@prisma/client';
// export const prisma = globalForPrisma.prisma ?? new PrismaClient({ ... });

Utilisez l'Option A si votre installation Prisma nécessite un argument adapter dans le constructeur PrismaClient. Utilisez l'Option B si new PrismaClient() fonctionne sans arguments. Laissez le compilateur vous dire laquelle est correcte.

Le motif globalThis empêche les instances en double pendant les rechargements à chaud (Next.js, nodemon, ts-node-dev).

Problème N+1

Charger des relations dans une boucle génère une requête par ligne.

// MAUVAIS : N+1 — une requête supplémentaire par utilisateur
const users = await prisma.user.findMany();
for (const user of users) {
  const posts = await prisma.post.findMany({ where: { authorId: user.id } });
}

// BON : une seule requête
const users = await prisma.user.findMany({ include: { posts: true } });

Avec relationJoins de Prisma 5+, la forme include utilise une seule JOIN. Sur de grands ensembles 1:N, cela peut augmenter la taille du jeu de résultats — testez les deux approches si la relation peut retourner plusieurs lignes par parent.

Exemples de Code

Pagination par Curseur (préférée pour les flux et les grands ensembles de données)

async function getPosts(cursor?: string, limit = 20) {
  const items = await prisma.post.findMany({
    where: { published: true },
    orderBy: [
      { createdAt: 'desc' },
      { id: 'desc' }, // tri secondaire empêche la pagination instable sur les timestamps en double
    ],
    take: limit + 1,
    ...(cursor && { cursor: { id: cursor }, skip: 1 }),
  });

  const hasNextPage = items.length > limit;
  if (hasNextPage) items.pop();

  return { items, nextCursor: hasNextPage ? items[items.length - 1].id : null };
}

Récupérez limit + 1 et retirez le dernier — méthode canonique pour détecter hasNextPage sans une requête de comptage supplémentaire. Incluez toujours un champ unique (par ex. id) comme orderBy secondaire pour éviter une pagination instable lorsque plusieurs lignes partagent le même timestamp. Utilisez la pagination par décalage uniquement lorsque les utilisateurs doivent sauter à des pages arbitraires (tableaux d'administration).

Suppression en Douceur

// Filtrez toujours explicitement — ne comptez pas sur un middleware (cache le comportement, difficile à déboguer)
const activeUsers = await prisma.user.findMany({ where: { deletedAt: null } });

await prisma.user.update({ where: { id }, data: { deletedAt: new Date() } });
await prisma.user.update({ where: { id }, data: { deletedAt: null } }); // restaurer

Gestion des Erreurs

import { Prisma } from '@prisma/client'; // ou le chemin du client généré pour votre configuration

try {
  await prisma.user.create({ data: { email } });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    if (e.code === 'P2002') throw new ConflictError('L\'email existe déjà');
    if (e.code === 'P2025') throw new NotFoundError('Enregistrement non trouvé');
    if (e.code === 'P2003') throw new BadRequestError('L\'enregistrement référencé n\'existe pas');
  }
  throw e;
}

Codes courants : P2002 violation d'unicité · P2025 non trouvé · P2003 violation de clé étrangère.

Attrapez à la limite du service et traduisez en erreurs de domaine. N'exposez jamais les messages bruts de Prisma aux consommateurs de l'API.

Pool de Connexions — Serverless

Intégrez les paramètres de connexion directement dans DATABASE_URL — la concaténation de chaînes échoue si l'URL a déjà des paramètres de requête (par ex. ?schema=public) :

# .env — recommandé : intégrer les paramètres dans l'URL
DATABASE_URL="postgresql://user:pass@host/db?connection_limit=1&pool_timeout=20"

# Avec un pooler externe (PgBouncer, pooler Supabase)
DATABASE_URL="postgresql://user:pass@host/db?pgbouncer=true&connection_limit=1"

// Vercel, AWS Lambda et environnements d'exécution serverless similaires :
// limiter le pool à 1 par instance ; connection_limit et pool_timeout contrôlés via DATABASE_URL

// Configuration basée sur adaptateur (si votre installation Prisma nécessite un adaptateur) :
import { PrismaClient } from '@prisma/client';
import { PrismaPg } from '@prisma/adapter-pg';

const prisma = new PrismaClient({
  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
});

// Configuration directe (si votre installation Prisma ne nécessite pas d'adaptateur) :
// const prisma = new PrismaClient();

Anti-Modèles

updateMany retourne un compteur, pas les enregistrements

// MAUVAIS : le résultat est { count: 2 } — users[0] est undefined
const users = await prisma.user.updateMany({ where: { role: 'GUEST' }, data: { role: 'USER' } });

// BON : capturez d'abord les ID, puis mettez à jour, puis récupérez uniquement les lignes affectées
const targets = await prisma.user.findMany({
  where: { role: 'GUEST' },
  select: { id: true },
});
const ids = targets.map((u) => u.id);
await prisma.user.updateMany({ where: { id: { in: ids } }, data: { role: 'USER' } });
const updated = await prisma.user.findMany({ where: { id: { in: ids } } });

Idem pour deleteMany — retourne { count: n }, jamais les lignes supprimées.

La forme interactive de $transaction expire après 5 secondes

// MAUVAIS : appel externe dans la transaction dépasse le délai par défaut de 5s → « Transaction already closed »
await prisma.$transaction(async (tx) => {
  const user = await tx.user.findUniqueOrThrow({ where: { id } });
  await sendWelcomeEmail(user.email); // appel externe
  await tx.user.update({ where: { id }, data: { emailSent: true } });
});

// BON : appels externes en dehors de la transaction
const user = await prisma.user.findUniqueOrThrow({ where: { id } });
await sendWelcomeEmail(user.email);
await prisma.user.update({ where: { id }, data: { emailSent: true } });

// Augmentez le délai d'attente uniquement lorsque le traitement par lots en a vraiment besoin
await prisma.$transaction(async (tx) => { ... }, { timeout: 30_000 });

migrate dev peut réinitialiser la base de données

migrate dev détecte la dérive du schéma et peut inviter à réinitialiser la BDD, supprimant toutes les données.

# JAMAIS sur le développement partagé, le staging ou la production
npx prisma migrate dev --name ajouter_colonne

# Sûr partout sauf développement local solo
npx prisma migrate deploy

# Vérifier la dérive sans appliquer
npx prisma migrate diff \
  --from-migrations ./prisma/migrations \
  --to-schema-datamodel ./prisma/schema.prisma \
  --shadow-database-url "$SHADOW_DATABASE_URL"

Modifier manuellement un fichier de migration casse les déploiements futurs

Prisma checksomme chaque fichier de migration. Modifier après application provoque une P3006 checksum mismatch sur chaque environnement où l'original a déjà été exécuté. Créez une nouvelle migration à la place.

Les changements de schéma cassants nécessitent une migration en plusieurs étapes

Ajouter NOT NULL à une colonne existante ou renommer une colonne en une seule migration verrouillera la table ou supprimera des données. Utilisez expand-and-contract :

# Étape 1 : créer la migration localement, puis déployer
npx prisma migrate dev --name ajouter_nouvelle_colonne   # local uniquement
npx prisma migrate deploy                                 # staging / production

// Étape 2 : renseigner les données (exécuté dans un script ou un job de migration, pas dans le shell)
await prisma.user.updateMany({ data: { newColumn: derivedValue } });

# Étape 3 : créer la migration de contrainte NOT NULL localement, puis déployer
npx prisma migrate dev --name rendre_nouvelle_colonne_obligatoire  # local uniquement
npx prisma migrate deploy                                           # staging / production

@updatedAt ne se déclenche pas sur updateMany

@updatedAt est défini automatiquement uniquement sur update et upsert. Les écritures en masse le laissent obsolète.

// MAUVAIS : updatedAt conserve son ancienne valeur
await prisma.post.updateMany({ where: { authorId }, data: { published: true } });

// BON
await prisma.post.updateMany({
  where: { authorId },
  data: { published: true, updatedAt: new Date() },
});

Suppression en douceur + findUniqueOrThrow fuit les enregistrements supprimés

findUniqueOrThrow lève P2025 uniquement lorsque la ligne n'existe pas dans la BDD. Les lignes supprimées en douceur existent toujours et sont retournées sans erreur.

findUniqueOrThrow nécessite un champ de contrainte unique dans where — ajouter deletedAt: null à côté de id casse le type car { id, deletedAt } n'est pas une contrainte unique composée. Utilisez findFirstOrThrow à la place.

// MAUVAIS : retourne un utilisateur supprimé en douceur
const user = await prisma.user.findUniqueOrThrow({ where: { id } });

// MAUVAIS : erreur de type Prisma — { id, deletedAt } n'est pas une contrainte unique
const user = await prisma.user.findUniqueOrThrow({ where: { id, deletedAt: null } });

// BON : findFirstOrThrow prend en charge les conditions where arbitraires
const user = await prisma.user.findFirstOrThrow({ where: { id, deletedAt: null } });

deleteMany sans where supprime toutes les lignes

// MAUVAIS : vide silencieusement la table
await prisma.post.deleteMany();

// BON
await prisma.post.deleteMany({ where: { authorId: userId } });

Bonnes Pratiques

Règle	Raison
migrate deploy dans CI/CD, migrate dev uniquement localement	migrate dev peut réinitialiser la BDD en cas de dérive
Mapper les entités vers des DTO de réponse	Empêche la fuite de champs internes