Skip to content
Learni
Voir tous les tutoriels
Bases de données

Comment intégrer PlanetScale avec Prisma en 2026

12 minINTERMEDIATE
PlanetScaleNext.jsPrismaServerlessMySQL
Read in English

Introduction

PlanetScale est une base de données MySQL serverless propulsée par Vitess, conçue pour scaler horizontalement sans downtime. Contrairement aux bases traditionnelles comme MySQL ou PostgreSQL, elle offre un système de branching inspiré de Git, des lectures ultra-rapides via des replicas Boost, et une compatibilité parfaite avec les ORMs comme Prisma.

Pourquoi l'utiliser en 2026 ? Les apps modernes explosent en trafic : PlanetScale gère des milliards de requêtes sans sharding manuel, avec une facturation au pixel près. Ce tutoriel intermédiaire vous montre comment intégrer PlanetScale dans une app Next.js avec Prisma : de la création de la DB au déploiement avec branching pour les features. À la fin, vous aurez une stack production-ready, scalable à l'infini. Temps estimé : 30 min. (128 mots)

Prérequis

  • Compte gratuit sur PlanetScale (inscription en 2 min)
  • Node.js 20+ et npm/yarn/pnpm
  • Connaissances de base en Next.js 15 et Prisma 6
  • Vercel CLI pour déploiement optionnel
  • Outil comme pscale installé via npm i -g @planetscale/cli

Initialiser le projet Next.js

terminal
npx create-next-app@latest mon-app-planetscale --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd mon-app-planetscale
npm install @prisma/client prisma @planetscale/database
npm install -D @types/node

Cette commande crée un projet Next.js 15 App Router complet avec TypeScript. On installe Prisma pour l'ORM, le driver PlanetScale pour les connexions directes, et les types Node. Évitez les templates vides pour gagner du temps sur la structure.

Créer la base de données PlanetScale

Connectez-vous à votre dashboard PlanetScale :

  1. Cliquez New database, nommez-la mon-app-db, région eu-west pour latence basse.
  2. Activez Branching (par défaut).
  3. Dans Connect, générez une Dev URL (format mysql://user:pass@aws.connect.psdb.cloud/db?sslaccept=strict).
  4. Copiez la Password (non réutilisable).

Analogie : Comme Git, créez un branch main pour prod et dev pour tests sans risquer les données live.

Configurer le schema Prisma

prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "mysql"
  url      = env("DATABASE_URL")
  // PlanetScale specifics
  directUrl = env("DIRECT_URL") // Pour migrations push
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  posts     Post[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String
  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

// Indexes pour perf PlanetScale
index on User(email)
index on Post(published, createdAt)

Ce schema définit deux modèles avec relations et indexes optimisés pour Vitess (pas de FK strictes par défaut, mais relations Prisma gérées). Utilisez DIRECT_URL pour migrations sur PlanetScale. Piège : Oubliez les indexes, les queries ralentissent sur gros volumes.

Lancer la première migration

terminal
echo "DATABASE_URL=\"mysql://username:password@host:3306/mon-app-db?sslaccept=strict&ssl={'rejectUnauthorized':true}\" > .env
npx prisma generate
npx prisma db push --accept-data-loss
npx prisma generate

Définissez DATABASE_URL depuis votre dashboard PlanetScale (remplacez les creds). db push applique le schema sans downtime sur PlanetScale. --accept-data-loss pour dev ; en prod, utilisez pscale branch create. Régénérez le client Prisma après.

Tester les queries avec Prisma Client

Créez une API route pour valider l'intégration. PlanetScale excelle en reads : utilisez connection pooling implicite via Prisma Accelerate (optionnel, gratuit 5GB).

Implémenter une API route CRUD

src/app/api/posts/route.ts
import { PrismaClient } from '@prisma/client';
import { NextRequest, NextResponse } from 'next/server';

const prisma = new PrismaClient();

export async function GET() {
  try {
    const posts = await prisma.post.findMany({
      where: { published: true },
      include: { author: true },
      orderBy: { createdAt: 'desc' },
    });
    return NextResponse.json(posts);
  } catch (error) {
    return NextResponse.json({ error: 'Erreur fetch posts' }, { status: 500 });
  }
}

export async function POST(request: NextRequest) {
  try {
    const { title, content, authorEmail } = await request.json();
    const author = await prisma.user.upsert({
      where: { email: authorEmail },
      update: {},
      create: { email: authorEmail, name: authorEmail },
    });
    const post = await prisma.post.create({
      data: {
        title,
        content,
        authorId: author.id,
      },
    });
    return NextResponse.json(post, { status: 201 });
  } catch (error) {
    return NextResponse.json({ error: 'Erreur création post' }, { status: 500 });
  }
}

// Cleanup Prisma
process.on('beforeExit', async () => {
  await prisma.$disconnect();
});

Cette route gère GET (lectures optimisées) et POST (création avec upsert pour users). Utilisez include pour joins efficaces sur PlanetScale. Ajoutez cleanup pour éviter fuites mémoire en serverless ; testez avec curl -X POST http://localhost:3000/api/posts -d '{"title":"Test","content":"Contenu","authorEmail":"test@example.com"}'.

Utiliser le CLI pour branching

terminal
pscale auth login
pscale database list
pscale branch create dev mon-app-db --org your-org
pscale branch list mon-app-db
pscale database branchpoint mon-app-db main dev
pscale repl connect mon-app-db dev

Authentifiez-vous, listez DBs, créez un branch dev depuis main. branchpoint marque le point de départ pour merges safe. repl connect pour shell MySQL local. Piège : Toujours merger via UI pour audits ; branches expirent après 7 jours inactifs.

Déployer sur Vercel avec secrets

Étapes :

  1. vercel env add DATABASE_URL production (collez la Prod URL de PlanetScale).
  2. vercel --prod.

PlanetScale + Vercel = combo parfait : serverless total, scaling auto.

Query directe avec @planetscale/database

src/app/api/raw-query/route.ts
import { connect } from '@planetscale/database';
import { NextResponse } from 'next/server';

const config = {
  url: process.env.DATABASE_URL!,
};

const db = connect(config);

export async function GET() {
  const [rows] = await db.execute('SELECT * FROM Post WHERE published = true ORDER BY createdAt DESC LIMIT 10');
  return NextResponse.json(rows);
}

Pour queries raw ultra-perf (sans ORM overhead), utilisez le driver officiel. Idéal pour analytics ou Vitess features comme sharding. execute retourne rows ; toujours paramétrer pour SQL injection (ici booléen safe).

Bonnes pratiques

  • Indexes stratégiques : Toujours indexer WHERE clauses courantes (ex: published, userId) pour Vitess.
  • Connection pooling : Activez Prisma Accelerate pour >100 req/s sans timeouts.
  • Branching workflow : dev → tests → pr → merge main pour CI/CD safe.
  • Monitoring : Utilisez PlanetScale Insights pour query perf ; limitez selects à <10ms.
  • SSL strict : Gardez sslaccept=strict en prod pour sécurité.

Erreurs courantes à éviter

  • Pas de DIRECT_URL : Migrations échouent sans elle (PlanetScale bloque DDL sur prod URL).
  • Foreign Keys manuelles : Vitess les supporte mal ; fiez-vous aux relations Prisma soft.
  • Forget cleanup Prisma : Fuites mémoire en serverless → crashes sur Vercel.
  • Ignore regions : Choisissez eu-west pour apps FR ; latence >200ms tue l'UX.

Pour aller plus loin

  • Docs officielles : PlanetScale + Prisma
  • Avancé : Boost pour read replicas, Vitess sharding.
  • Formations Learni Group sur bases serverless et Next.js avancées.
  • Repo exemple : Forkez ce tuto sur GitHub pour expérimenter.