Mettre à jour Prisma à la version v7 dans une application Next.js avec des adaptateurs de pilote

Prisma v7 intègre les paramètres par défaut des modules ES, une nouvelle méthode d’instanciation du client ainsi que des adaptateurs de pilote. Mettre à jour une application Next.js consiste en une série d’étapes à suivre plutôt qu’en une simple augmentation de version.

Exigences minimales

Node.js 20.19+ (22.x recommandé), TypeScript 5.4+, ainsi qu’une version de Next.js compatible avec vos paramètres ESM.

Étapes de mise à jour

1. Mettre à jour les dépendances

Augmenter simultanément les versions de prisma et @prisma/client à v7.

2. Activer le support des modules ES

Définir "type": "module" là où c’est requis et corriger les extensions/chemins d’import que le format CJS tolérait auparavant.

3. Mettre à jour le schéma Prisma

Appliquer les modifications du générateur/fournisseur documentées pour v7 ; régénérer le schéma après les modifications.

4. Installer dotenv si nécessaire

Chargez l’environnement explicitement lorsque les nouveaux points d’entrée ne chargent plus automatiquement .env de la manière traditionnelle.

5. Créer le fichier de configuration Prisma

Centralisez les adresses URL des sources de données ainsi que la configuration des adaptateurs dans le module de configuration pris en charge.

6. Mettre à jour l’instanciation du client avec des adaptateurs de pilote

npm install @prisma/client@7
npm install -D prisma@7

{
  "type": "module",
  "scripts": {...}
}

generator client {
  provider = "prisma-client-js"
  engineType = "binary"
  output = "./generated"
}

generator client {
  provider = "prisma-client"
}

npm install dotenv

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

npm install @prisma/adapter-pg

// db/index.ts

import { PrismaClient } from '@prisma/client';

const globalForPrisma = global as unknown as {
  prisma: PrismaClient;
};
const prisma =
  globalForPrisma.prisma ||
  new PrismaClient();

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

export default prisma;

// db/index.ts

import { PrismaClient } from "@prisma/client";
import { Pool } from "pg";
import { PrismaPg } from "@prisma/adapter-pg";

// postgreSQL adapter for prisma 7
const pool = new Pool({
  connectionString: process.env.DATABASE_URL!,
});

const adapter = new PrismaPg(pool);

const globalForPrisma = global as unknown as {
  prisma: PrismaClient;
};

const prisma =
  globalForPrisma.prisma ||
  new PrismaClient({
    adapter,
  });

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

export default prisma;

// app/api/users/route.ts

import { prisma } from '@/lib/prisma';
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    const users = await prisma.user.findMany();
    return NextResponse.json(users);
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch users' },
      { status: 500 }
    );
  }
}

npx prisma generate

npm run dev

rm -rf node_modules package-lock.json
npm install
npx prisma generate

Utilisez l’adaptateur correspondant à votre pilote de base de données au lieu de compter sur des constructeurs obsolètes.

8. Régénérer le client Prisma

Exécutez prisma generate une fois que le schéma et la configuration sont finalisés.

9. Tester votre migration

Exécutez les migrations sur une base de données temporaire, testez les gestionnaires d’URL critiques de Next.js, et vérifiez que les imports en temps de exécution sont résolus correctement.

Problèmes courants

• Importations mixtes CJS/ESM dans lib/prisma.ts
• Moteur Node incorrect sur CI
• Oubli de régénérer le client après des modifications d’adaptateur
• Environnement Edge qui importe des pilotes uniquement compatibles Node

Intégrez les modifications de l’adaptateur et d’ESM dans une seule PR, en incluant un test de fonctionnement sur les chemins create/read/update.

Conservez un unique singleton de client Prisma pour les environnements serveur afin d’éviter l’épuisement des pools de connexions lors du HMR en développement dans Next.js.

Dokumentez quelles routes s’exécutent sur Edge et celles qui fonctionnent sous Node ; les adaptateurs diffèrent, et des solutions de fallback silencieuses provoquent des pannes imprévisibles uniquement en production.

Conservez un unique singleton de client Prisma pour les environnements serveur afin d’éviter l’épuisement des pools de connexions lors du HMR en développement dans Next.js.

Après avoir régénéré le client, supprimez les caches de compilation .next obsolètes afin que Next.js ne charge pas une version ancienne du client Prisma issue d’une compilation précédente.

Vérifiez les paramètres de gestion des pools de connexions lors du changement d’adaptateurs : les serveurs serverless et les serveurs Node à exécution prolongée nécessitent des tailles de pool différentes.