Mettre en place Prisma 7 dans un projet Next.js 16 TypeScript
Apprenez à installer, configurer et migrer Prisma 7 avec PostgreSQL dans une application Next.js 16, puis créez un client singleton pour éviter les fuites de connexions.
Cette démarche explique comment intégrer Prisma 7 dans une application Next.js 16 qui communique avec PostgreSQL, en utilisant TypeScript et pnpm comme gestionnaire de paquets.
Étape 1 : Ajouter les packages Prisma
pnpm add prisma @prisma/client @prisma/adapter-pg
- prisma — l’outil en ligne de commande que vous utiliserez pour exécuter les migrations, générer le client et gérer votre schéma.
- @prisma/client — la bibliothèque client générée que le code de votre application appellera directement.
- @prisma/adapter-pg — l’adaptateur du pilote PostgreSQL introduit par Prisma 7 pour se connecter à Postgres.
Avec ces trois packages installés, vous êtes prêt à initialiser la configuration Prisma.
Étape 2 : Initialiser Prisma
pnpm dlx prisma init
L’exécution de ce script crée les fichiers et dossiers de base nécessaires pour commencer.
prisma.config.ts
prisma/
└── schema.prisma
Comprendre prisma.config.ts
Ce fichier contient les paramètres dont Prisma a besoin pour fonctionner, y compris la manière dont il se connecte à votre base de données et le comportement du générateur de client.
import "dotenv/config";
import { defineConfig } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
datasource: {
url: process.env["DATABASE_URL"],
},
});
Comprendre schema.prisma
Toute table que vous prévoyez de stocker dans PostgreSQL apparaîtra ici sous forme de définition de modèle.
generator client {
provider = "prisma-client"
output = "../lib/generated/prisma"
}
datasource db {
provider = "postgresql"
}
// models that You want to create
Étape 3 : Diriger Prisma vers votre base de données
Prisma a besoin d’une chaîne de connexion avant de pouvoir communiquer avec votre base de données. Vous pouvez en obtenir une auprès d’un fournisseur hébergé comme Neon, ou en exécutant une instance de Postgres localement via Docker.
DATABASE_URL="postgresql://username:password@localhost:5432/my_database"
Dès que cette variable d’environnement est définie, Prisma peut se connecter à votre base de données.
Étape 4 : Définir un modèle initial
Le Prisma Client ne peut pas être généré tant qu’au moins un modèle n’existe pas dans le schéma.
Puisque la base de données est encore vide à ce stade, ajoutez un modèle de remplacement minimal afin que Prisma ait quelque chose sur quoi travailler.
model Test {
id Int @id @default(autoincrement())
}
Le but ici n’est pas de créer une table significative — il s’agit simplement de fournir au générateur un schéma valide sur lequel s’appuyer.
Étape 5 : Appliquer votre première migration
Ensuite, transformez ce schéma en véritables tables de base de données en exécutant une migration.
pnpm dlx prisma migrate dev
Cette seule commande gère automatiquement plusieurs choses :
- Elle génère un nouveau fichier de migration.
- Elle applique cette migration à la base de données configurée.
- Elle maintient la structure de votre base de données en temps réel en synchronisation avec ce qui est déclaré dans
schema.prisma.
Lorsqu’elle se termine avec succès, la table Test existera dans votre base de données.
Étape 6 : Générer le client Prisma
L’un des changements les plus notables dans Prisma 7 est que le client n’est plus généré automatiquement pour vous.
Vous devez maintenant déclencher sa génération explicitement.
pnpm dlx prisma generate dev
Lorsque cette étape est terminée, Prisma crée un client entièrement typé adapté à votre schéma.
Ce client expose toutes les méthodes nécessaires pour interroger et modifier vos données.
generated/
└── prisma/
Chaque modèle défini dans votre schéma est désormais exposé sous forme d’une API TypeScript typée distincte.
Étape 7 : Créer un client Prisma Singleton
Au lieu d’instancier un nouveau client Prisma à chaque requête, la meilleure pratique consiste à réutiliser une seule instance partagée dans toute votre application.
File: lib/prisma.ts
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";
const globalForPrisma = globalThis as unknown as {
prisma: PrismaClient | undefined;
};
function createPrismaClient() {
const url = process.env.DATABASE_URL;
if (!url) {
throw new Error("DATABASE_URL is not set");
}
const adapter = new PrismaPg({ connectionString: url });
return new PrismaClient({ adapter });
}
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
if (process.env.NODE_ENV !== "production") {
globalForPrisma.prisma = prisma;
}
Pourquoi un Singleton est important ici
Next.js recharge en temps réel les modules constamment pendant le développement.
Si un nouveau PrismaClient est créé à chaque recharge, vous finissez par ouvrir bien plus de connexions au base de données que ce à quoi vous vous attendiez.
Si cela n’est pas corrigé, cela se traduira finalement par une erreur du type suivant :
Too many database connections
L’utilisation du pattern Singleton garantit qu’une seule instance de Prisma Client persiste tout au long de la durée de vie de l’application.
C’est l’approche recommandée par Prisma lui-même pour les projets Next.js.
Étape 8 : Utiliser le client dans toute votre application
Avec cette instance de client partagée en place, vous pouvez l’importer depuis n’importe où dans votre projet.
import { prisma } from "@/lib/prisma";
À partir de là, tout composant serveur, toute route API ou toute action serveur a un accès direct à votre base de données.
Pour en savoir plus sur cette configuration, consultez la documentation officielle de Prisma concernant l’intégration avec Next.js, disponible à prisma.io/docs/guides/nextjs.
Lectures complémentaires
- Créer des templates de démarrage reutilisables Next.js pour éviter le code générique — Découvrez comment un développeur a remplacé les tâches répétitives de nettoyage dans Next.js par une série croissante de templates de démarrage minimalistes pour des boutiques en ligne et des pages d’accueil.
- Migrer de Prisma à Drizzle : un retour sur six mois — Un développeur partage des benchmarks et des compromis tirés de la transition d’un stack PostgreSQL TypeScript basé sur Prisma vers l’ORM Drizzle.