À propos de ce cours
Objectifs de la leçon
- Décrire un modèle de données dans schema.prisma.
- Générer le client Prisma et créer les tables par migration.
- Intégrer Prisma dans NestJS avec un PrismaService.
- Écrire un CRUD avec relations, agrégats et transactions.
- Traduire les erreurs Prisma en réponses HTTP.
Prisma, une autre approche
Avec TypeORM, le modèle est décrit par des classes décorées. Prisma inverse la démarche : le modèle est décrit dans un fichier dédié, schema.prisma, avec son propre langage, très lisible. À partir de ce fichier, Prisma :
- génère un client TypeScript entièrement typé (
prisma.stagiaire.findMany(…)) : l'éditeur connaît chaque champ, chaque relation, et le type exact du résultat selon les options demandées ; - génère les migrations SQL pour créer et faire évoluer les tables.
Le schéma est la source de vérité du client et des migrations.
Installation
npm install -D prisma@7 # la CLI
npm install @prisma/client@7 @prisma/adapter-mariadb@7 dotenv
npx prisma init --datasource-provider mysql # crée prisma/schema.prisma, prisma.config.ts et .env
Fixez la version. Au moment où ce cours a été écrit, npm install prisma installait une version 8 préliminaire (étiquetée rc) alors que @prisma/client restait en 7.10. Le client et la CLI doivent avoir la même version : écrivez prisma@7 et @prisma/client@7. Les exemples ont été exécutés avec Prisma 7.10.1.
Le schéma
📄 prisma/schema.prisma
generator client {
provider = "prisma-client" // nouveau générateur (Prisma 7)
output = "../src/generated/prisma" // le client est généré DANS le projet
}
datasource db {
provider = "mysql" // l'URL est dans prisma.config.ts (Prisma 7)
}
model Groupe {
id Int @id @default(autoincrement())
code String @unique @db.VarChar(10)
intitule String @db.VarChar(80)
stagiaires Stagiaire[]
@@map("groupes")
}
model Stagiaire {
id Int @id @default(autoincrement())
nom String @db.VarChar(50)
prenom String @db.VarChar(50)
email String @unique @db.VarChar(120)
groupeId Int? @map("groupe_id")
groupe Groupe? @relation(fields: [groupeId], references: [id], onDelete: SetNull)
notes Note[]
creeLe DateTime @default(now()) @map("cree_le")
@@map("stagiaires")
}
model Note {
id Int @id @default(autoincrement())
matiere String @db.VarChar(30)
valeur Decimal @db.Decimal(4, 2)
stagiaireId Int @map("stagiaire_id")
stagiaire Stagiaire @relation(fields: [stagiaireId], references: [id], onDelete: Cascade)
@@map("notes")
}
| Écriture | Signification |
|---|---|
Int @id @default(autoincrement()) | clé primaire auto-incrémentée |
String @unique @db.VarChar(10) | chaîne unique, type MySQL précis |
Int? | champ facultatif (NULL autorisé) |
@relation(fields: [groupeId], references: [id], onDelete: SetNull) | clé étrangère et comportement à la suppression |
Stagiaire[] | côté « plusieurs » de la relation (pas de colonne) |
@map("groupe_id"), @@map("stagiaires") | noms de colonne et de table en base |
DateTime @default(now()) | date de création automatique |
📄 prisma.config.ts
import 'dotenv/config';
import { defineConfig, env } from 'prisma/config';
export default defineConfig({
schema: 'prisma/schema.prisma',
migrations: { path: 'prisma/migrations' },
datasource: { url: env('DATABASE_URL') },
});
📄 .env
DATABASE_URL=mysql://apc_dev:secret_dev@localhost:3306/formation_dev
DB_HOTE=localhost
DB_PORT=3306
DB_UTILISATEUR=apc_dev
DB_MOT_DE_PASSE=secret_dev
DB_NOM=formation_dev
Ce qui change avec Prisma 7 par rapport aux nombreux tutoriels écrits pour Prisma 5 ou 6 : (1) le générateur s'appelle prisma-client et le client est généré dans votre projet (output obligatoire), on l'importe depuis ./generated/prisma/client et non depuis @prisma/client; (2) l'URL de la base n'est plus dans schema.prisma mais dans prisma.config.ts; (3) le client se connecte par un adaptateur de pilote écrit en TypeScript (@prisma/adapter-mariadb pour MySQL et MariaDB), sans moteur binaire.
Générer le client et créer les tables
npx prisma generate # génère le client typé dans src/generated/prisma
npx prisma migrate dev --name init # crée prisma/migrations/<horodatage>_init/migration.sql et l'applique
npx prisma studio # interface web pour consulter les données
Génération du client, puis requêtes de l'API :
$ npx prisma generate
✔ Generated Prisma Client (7.10.1) to ./src/generated/prisma in 60ms
Loaded Prisma config from prisma.config.ts.
Prisma schema loaded from prisma/schema.prisma.
SQL> SELECT `groupes`.`id` FROM `groupes` WHERE (`groupes`.`code` = ? AND 1=1) LIMIT ? OFFSET ? -- ["DEV101","1","0"]
SQL> INSERT INTO `stagiaires` (`nom`,`prenom`,`email`,`groupe_id`,`cree_le`) VALUES (?,?,?,?,?) -- ["Ben Ali","Sami","sami@exemple.tn",1,"2026-11-15T08:07:04.039Z"]
SQL> SELECT `stagiaires`.`id`, `stagiaires`.`nom`, `stagiaires`.`prenom`, `stagiaires`.`email`, `stagiaires`.`groupe_id`, `stagiaires`.`cree_le` FROM `stagiaires` WHERE `stagiaires`.`id` = ? LIMIT ? OFFSET ? -- ["1","1","0"]
SQL> SELECT `groupes`.`id`, `groupes`.`code`, `groupes`.`intitule` FROM `groupes` WHERE `groupes`.`id` = ? -- [1]
SQL> -- Implicit "COMMIT" query via underlying driver -- []
POST /api/stagiaires → 201 {"id":1,"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupeId":1,"creeLe":"…","groupe":{"id":1,"code":"DEV101","intitule":"Développement web 1"}}
POST /api/stagiaires → 201 {"id":2,"nom":"Trabelsi","prenom":"Ines","email":"ines@exemple.tn","groupeId":2,"creeLe":"…","groupe":{"id":2,"code":"DEV102","intitule":"Développement web 2"}}
POST /api/stagiaires → 201 {"id":3,"nom":"Gharbi","prenom":"Yassine","email":"yassine@exemple.tn","groupeId":null,"creeLe":"…","groupe":null}
POST /api/stagiaires → 409 {"message":"L'e-mail sami@exemple.tn est déjà utilisé","error":"Conflict","statusCode":409}
POST /api/stagiaires → 404 {"message":"Groupe RES999 introuvable","error":"Not Found","statusCode":404}
POST /api/stagiaires/1/notes → 201 {"notes":2,"moyenne":"13.75"}
POST /api/stagiaires/2/notes → 201 {"notes":1,"moyenne":"17"}
SQL> SELECT `stagiaires`.`id`, `stagiaires`.`nom`, `stagiaires`.`prenom`, `stagiaires`.`email`, `stagiaires`.`groupe_id`, `stagiaires`.`cree_le`, COALESCE(`aggr_selection_0_Note`.`_aggr_count_notes`, 0) AS `_aggr_count_notes` FROM `stagiaires` LEFT JOIN (SELECT `notes`.`stagiaire_id`, COUNT(*) AS `_aggr_count_notes` FROM `notes` WHERE 1=1 GROUP BY `notes`.`stagiaire_id`) AS `aggr_selection_0_Note` ON (`stagiaires`.`id` = `aggr_selection_0_Note`.`stagiaire_id`) LEFT JOIN `groupes` AS `j0` ON (`j0`.`id`) = (`stagiaires`.`groupe_id`) WHERE (`j0`.`code` = ? AND (`j0`.`id` IS NOT NULL)) ORDER BY `stagiaires`.`nom` ASC, `stagiaires`.`prenom` ASC -- ["DEV101"]
SQL> SELECT `groupes`.`id`, `groupes`.`code` FROM `groupes` WHERE `groupes`.`id` IN (?) -- [1]
GET /api/stagiaires?groupe=DEV101 → 200 [{"id":1,"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupeId":1,"creeLe":"…","groupe":{"code":"DEV101"},"_count":{"notes":2}}]
GET /api/stagiaires/1 → 200 {"id":1,"nom":"Ben Ali","prenom":"Sami","email":"sami@exemple.tn","groupeId":1,"creeLe":"…","groupe":{"id":1,"code":"DEV101","intitule":"Développement web 1"},"notes":[{"id":2,"matiere":"JS","valeur":"12.5","stagiaireId":1},{"id":1,"matiere":"SQL","valeur":"15","stagiaireId":1}]}
GET /api/stagiaires/moyennes → 200 [{"groupe":"DEV101","moyenne":"13.75"},{"groupe":"DEV102","moyenne":"17"}]
PATCH /api/stagiaires/3 → 200 {"id":3,"nom":"Gharbi","prenom":"Yassine","email":"yassine@exemple.tn","groupeId":2,"creeLe":"…"}
PATCH /api/stagiaires/99 → 404 {"message":"Stagiaire 99 ou groupe introuvable","error":"Not Found","statusCode":404}
DELETE /api/stagiaires/1 → 204
DELETE /api/stagiaires/1 → 404 {"message":"Stagiaire 1 introuvable","error":"Not Found","statusCode":404}
Notes restantes en base : 1
migrate dev compare le schéma à la base, écrit un fichier migration.sql (à versionner, comme avec TypeORM, leçon 11.8), l'applique et régénère le client. En production, on utilise npx prisma migrate deploy, qui applique les migrations sans en créer. Ajoutez src/generated au .gitignore: le client se régénère à partir du schéma (script postinstall: "prisma generate").
Dans l'environnement où les exemples ont été exécutés, le moteur de migration de Prisma (un programme téléchargé à la première utilisation) n'était pas accessible : les tables ont été créées directement en SQL, avec la même structure que la migration. Toutes les requêtes affichées ci-dessus ont, elles, été réellement exécutées par le client Prisma sur MySQL/MariaDB.
Le PrismaService
📄 src/prisma/prisma.service.ts
import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import { PrismaClient } from '../generated/prisma/client';
@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
constructor(config: ConfigService) {
// Prisma 7 : la connexion passe par un « adaptateur » de pilote (ici MariaDB/MySQL)
const adapter = new PrismaMariaDb({
host: config.getOrThrow('DB_HOTE'),
port: Number(config.get('DB_PORT', 3306)),
user: config.getOrThrow('DB_UTILISATEUR'),
password: config.get('DB_MOT_DE_PASSE', ''),
database: config.getOrThrow('DB_NOM'),
connectionLimit: 5,
});
super({ adapter, log: [{ emit: 'event', level: 'query' }] });
}
async onModuleInit() {
this.$on('query' as never, (e: { query: string; params: string }) => {
if ((globalThis as any).SQL) console.log(` SQL> ${e.query} -- ${e.params}`);
});
await this.$connect();
}
async onModuleDestroy() {
await this.$disconnect();
}
}
📄 src/prisma/prisma.module.ts
import { Global, Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';
@Global() // PrismaService injectable partout
@Module({ providers: [PrismaService], exports: [PrismaService] })
export class PrismaModule {}
PrismaServicehérite du client : il possèdethis.stagiaire,this.$transaction… et devient injectable comme n'importe quel service.- Les crochets
onModuleInit/onModuleDestroy(leçon 5.6) ouvrent et ferment la connexion avec l'application. - L'option
loget$on('query')affichent le SQL généré ; on peut les retirer en production. @Global()évite d'importerPrismaModulepartout (commeisGlobalpour la configuration).
Le service des stagiaires
📄 src/stagiaires/stagiaires.service.ts
import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
import { Prisma } from '../generated/prisma/client';
import { PrismaService } from '../prisma/prisma.service';
import { CreerStagiaireDto, ModifierStagiaireDto } from './stagiaire.dto';
@Injectable()
export class StagiairesService {
constructor(private readonly prisma: PrismaService) {}
findAll(groupe?: string) {
return this.prisma.stagiaire.findMany({
where: groupe ? { groupe: { code: groupe } } : undefined,
include: { groupe: { select: { code: true } }, _count: { select: { notes: true } } },
orderBy: [{ nom: 'asc' }, { prenom: 'asc' }],
});
}
async findOne(id: number) {
const stagiaire = await this.prisma.stagiaire.findUnique({
where: { id },
include: { groupe: true, notes: { orderBy: { matiere: 'asc' } } },
});
if (!stagiaire) throw new NotFoundException(`Stagiaire ${id} introuvable`);
return stagiaire;
}
async create({ groupe, ...donnees }: CreerStagiaireDto) {
try {
return await this.prisma.stagiaire.create({
data: { ...donnees, ...(groupe ? { groupe: { connect: { code: groupe } } } : {}) }, // relier par une clé unique
include: { groupe: true },
});
} catch (e) {
throw this.traduire(e, `L'e-mail ${donnees.email} est déjà utilisé`, `Groupe ${groupe} introuvable`);
}
}
async update(id: number, { groupe, ...donnees }: ModifierStagiaireDto) {
try {
return await this.prisma.stagiaire.update({
where: { id },
data: { ...donnees, ...(groupe ? { groupe: { connect: { code: groupe } } } : {}) },
});
} catch (e) {
throw this.traduire(e, 'Cet e-mail est déjà utilisé', `Stagiaire ${id} ou groupe introuvable`);
}
}
async remove(id: number) {
try {
await this.prisma.stagiaire.delete({ where: { id } });
} catch (e) {
throw this.traduire(e, '', `Stagiaire ${id} introuvable`);
}
}
// Ajouter plusieurs notes : une seule transaction
ajouterNotes(id: number, notes: { matiere: string; valeur: number }[]) {
return this.prisma.$transaction(async (tx) => {
await tx.note.createMany({ data: notes.map((n) => ({ ...n, stagiaireId: id })) });
const { _avg, _count } = await tx.note.aggregate({ where: { stagiaireId: id }, _avg: { valeur: true }, _count: true });
return { notes: _count, moyenne: _avg.valeur };
});
}
moyennesParGroupe() {
return this.prisma.$queryRaw<{ groupe: string; moyenne: string }[]>`
SELECT g.code AS groupe, ROUND(AVG(n.valeur), 2) AS moyenne
FROM groupes g JOIN stagiaires s ON s.groupe_id = g.id JOIN notes n ON n.stagiaire_id = s.id
GROUP BY g.id ORDER BY g.code`;
}
// Codes d'erreur Prisma : P2002 = contrainte unique, P2025 = enregistrement introuvable
private traduire(e: unknown, doublon: string, introuvable = 'Introuvable') {
if (e instanceof Prisma.PrismaClientKnownRequestError) {
if (e.code === 'P2002') return new ConflictException(doublon);
if (e.code === 'P2025') return new NotFoundException(introuvable);
}
return e;
}
}
📄 src/stagiaires/stagiaires.controller.ts
import { Body, Controller, Delete, Get, HttpCode, Param, ParseIntPipe, Patch, Post, Query } from '@nestjs/common';
import { CreerStagiaireDto, ModifierStagiaireDto } from './stagiaire.dto';
import { StagiairesService } from './stagiaires.service';
@Controller('stagiaires')
export class StagiairesController {
constructor(private readonly stagiairesService: StagiairesService) {}
@Get('moyennes')
moyennes() {
return this.stagiairesService.moyennesParGroupe();
}
@Get()
findAll(@Query('groupe') groupe?: string) {
return this.stagiairesService.findAll(groupe);
}
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
return this.stagiairesService.findOne(id);
}
@Post()
create(@Body() dto: CreerStagiaireDto) {
return this.stagiairesService.create(dto);
}
@Post(':id/notes')
notes(@Param('id', ParseIntPipe) id: number, @Body() notes: { matiere: string; valeur: number }[]) {
return this.stagiairesService.ajouterNotes(id, notes);
}
@Patch(':id')
update(@Param('id', ParseIntPipe) id: number, @Body() dto: ModifierStagiaireDto) {
return this.stagiairesService.update(id, dto);
}
@Delete(':id')
@HttpCode(204)
remove(@Param('id', ParseIntPipe) id: number) {
return this.stagiairesService.remove(id);
}
}
const prisma = app.get(PrismaService);
await prisma.groupe.createMany({ data: [{ code: 'DEV101', intitule: 'Développement web 1' }, { code: 'DEV102', intitule: 'Développement web 2' }] });
const b = '/api/stagiaires';
await appel('POST', b, { corps: { nom: 'Ben Ali', prenom: 'Sami', email: 'sami@exemple.tn', groupe: 'DEV101' } });
await appel('POST', b, { corps: { nom: 'Trabelsi', prenom: 'Ines', email: 'ines@exemple.tn', groupe: 'DEV102' } });
await appel('POST', b, { corps: { nom: 'Gharbi', prenom: 'Yassine', email: 'yassine@exemple.tn' } });
await appel('POST', b, { corps: { nom: 'Copie', prenom: 'Sami', email: 'sami@exemple.tn' } });
await appel('POST', b, { corps: { nom: 'Inconnu', prenom: 'Xavier', email: 'x@exemple.tn', groupe: 'RES999' } });
await appel('POST', `${b}/1/notes`, { brut: JSON.stringify([{ matiere: 'SQL', valeur: 15 }, { matiere: 'JS', valeur: 12.5 }]) });
await appel('POST', `${b}/2/notes`, { brut: JSON.stringify([{ matiere: 'SQL', valeur: 17 }]) });
await appel('GET', `${b}?groupe=DEV101`);
await appel('GET', `${b}/1`);
await appel('GET', `${b}/moyennes`);
await appel('PATCH', `${b}/3`, { corps: { groupe: 'DEV102' } });
await appel('PATCH', `${b}/99`, { corps: { nom: 'Fantôme' } });
await appel('DELETE', `${b}/1`);
await appel('DELETE', `${b}/1`);
console.log('Notes restantes en base :', await prisma.note.count());
Lecture des résultats
- Création:
groupe: { connect: { code: 'DEV101' } }relie le stagiaire au groupe par une clé unique ; Prisma cherche le groupe, insère le stagiaire, puis relit le tout pour l'include. - Erreurs: un e-mail en double déclenche
P2002(→ 409), un groupe inexistant à relier ou un stagiaire inexistant à modifier ou supprimer déclencheP2025(→ 404). Ces codes sont stables et documentés : on les traduit en un seul endroit. - Lecture:
where: { groupe: { code } }filtre sur une relation ;includecharge les relations ;_countcompte les notes sans les charger. Le résultat est typé : l'éditeur sait quegroupe.codeexiste, mais pasgroupe.intitule(non sélectionné). - Décimaux:
valeuret les moyennes sont renvoyées en chaînes ("12.5","13.75") : Prisma utilise un typeDecimalexact, sérialisé en texte. Même situation qu'avec TypeORM (leçon 11.3) ; convertir avecNumber()si nécessaire. - Transaction:
$transaction(async (tx) => …)fonctionne comme celle de TypeORM ; toute exception annule l'ensemble. - SQL brut:
$queryRawavec une chaîne modèle (template literal) paramètre automatiquement les valeurs${…}: pas d'injection possible.$queryRawUnsafe, lui, ne protège pas. - La suppression du stagiaire a supprimé ses notes (
onDelete: Cascade) : il reste 1 note, celle de Trabelsi.
Prisma ou TypeORM ?
| TypeORM | Prisma | |
|---|---|---|
| Modèle | classes + décorateurs (style NestJS) | fichier schema.prisma |
| Typage des résultats | l'entité, même si des relations ne sont pas chargées | exact selon select / include |
| Requêtes complexes | QueryBuilder très complet | API objet + $queryRaw |
| Migrations | générées depuis les entités | générées depuis le schéma, très fiables |
| Intégration NestJS | module officiel | un service à écrire (quelques lignes) |
| Outils | — | Prisma Studio, formatage du schéma |
Les deux sont de bons choix ; l'important est d'être cohérent dans un projet. Le reste du cours continue avec TypeORM.
Activités
Activité 1 Ajouter un modèle
Ajoutez au schéma un modèle Competence (libellé unique) et une relation plusieurs-à-plusieurs avec Stagiaire. Quelle table Prisma crée-t-il ? Écrivez l'appel qui ajoute la compétence « CSS » au stagiaire 2.
Voir le corrigé
model Competence {
id Int @id @default(autoincrement())
libelle String @unique @db.VarChar(40)
stagiaires Stagiaire[]
@@map("competences")
}
model Stagiaire {
// …
competences Competence[]
}
await prisma.stagiaire.update({
where: { id: 2 },
data: { competences: { connect: { libelle: 'CSS' } } },
});
Pour une relation implicite, Prisma crée une table de jointure nommée _CompetenceToStagiaire. Pour la nommer ou y ajouter des colonnes (niveau, date), on déclare un modèle intermédiaire explicite.
Activité 2 Pagination
Écrivez findPage(page, limite) qui renvoie les stagiaires triés par nom et le total, en une transaction de lecture.
Voir le corrigé
async findPage(page = 1, limite = 10) {
const [donnees, total] = await this.prisma.$transaction([
this.prisma.stagiaire.findMany({ orderBy: { nom: 'asc' }, skip: (page - 1) * limite, take: limite }),
this.prisma.stagiaire.count(),
]);
return { donnees, meta: { total, page, limite, pages: Math.max(1, Math.ceil(total / limite)) } };
}
La forme tableau de $transaction exécute les requêtes dans une même transaction et renvoie leurs résultats dans l'ordre.
Activité 3 Moyenne par stagiaire
Avec groupBy, calculez la moyenne et le nombre de notes par stagiaire, uniquement pour les moyennes supérieures ou égales à 10.
Voir le corrigé
const resultats = await this.prisma.note.groupBy({
by: ['stagiaireId'],
_avg: { valeur: true },
_count: { _all: true },
having: { valeur: { _avg: { gte: 10 } } },
orderBy: { _avg: { valeur: 'desc' } },
});
Activité 4 Porter le TP 7 sur Prisma
Dans une branche prisma de votre dépôt api-bibliotheque, écrivez le schéma Prisma équivalent aux cinq entités (avec @@map et @map pour garder les mêmes noms de tables et de colonnes), générez le client et réécrivez LivresService.findOne et EmpruntsService.emprunter. Que remarquez-vous pour le verrou pessimiste ?
Voir le corrigé
Le schéma se déduit directement des entités. Avec npx prisma db pull, Prisma peut même le générer à partir de la base existante. Pour le verrou : Prisma n'a pas d'option lock comme TypeORM. On utilise une requête brute dans la transaction (await tx.$queryRaw`SELECT disponibles FROM livres WHERE id = ${id} FOR UPDATE`), ou mieux, la mise à jour conditionnelle : tx.livre.updateMany({ where: { id, disponibles: { gt: 0 } }, data: { disponibles: { decrement: 1 } } }), et vérifier count.
À retenir
- Prisma : modèle dans schema.prisma, client typé généré, migrations générées.
- Prisma 7 : générateur prisma-client (output dans le projet), URL dans prisma.config.ts, adaptateur de pilote (@prisma/adapter-mariadb).
- Fixer la même version pour prisma et @prisma/client (prisma@7).
- PrismaService extends PrismaClient + onModuleInit/onModuleDestroy, exporté par un module global.
- Erreurs : P2002 (unicité) → 409, P2025 (introuvable) → 404 ; $queryRaw paramétré, $transaction.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !