Cours Vibe coding avec Claude Code · Module 14: Clone de Pinterest

Le registre des trésors : une base de données pour les pins et les tableaux

11 min de lecture
Dans cette leçon13

Crée un tableau "Cartes du marché" puis arrête le serveur et relance-le. Le tableau a disparu. Les coffres de la leçon 13_2 dorment dans un entrepôt sur globalThis, c'est-à-dire dans la mémoire d'un seul processus Node, et les pins dans une liste de lib/pins.ts. Chaque redémarrage repart de zéro, alors qu'il faut un livre du port qui survive à la tempête : une base de données. Pour lui parler, Claude utilisera Prisma ORM. Un ORM est une bibliothèque qui transforme les lignes des tables en objets TypeScript : au lieu d'écrire du SQL à la main, tu appelles prisma.board.findMany() et tu obtiens des types.

Ce que tu vas apprendre

  • demander à Claude de lire la documentation de la bonne version avant d'installer quoi que ce soit, et reconnaître le piège des versions ;
  • lancer une base locale sans compte et sans Docker, et saisir son adresse de façon que l'agent ne la voie pas ;
  • lire la migration SQL avant qu'elle touche la base ;
  • déplacer les tableaux dans la base en laissant intactes les règles d'accès de la leçon 13_2.

Quatre mots avant la traversée

Le schéma (prisma/schema.prisma) décrit les tables dans le langage de Prisma. Une migration est un fichier SQL qui transforme la base d'hier en base d'aujourd'hui, et qui va dans le dépôt. Le client est du code TypeScript généré à partir du schéma, avec une méthode pour chaque table. L'adaptateur est le pilote par lequel le client se connecte à PostgreSQL.

Un piège du calendrier, état de novembre 2026 : npm, sous l'étiquette latest, donne Prisma ORM 8, qui est encore une version candidate (release candidate). Prisma 7 est pleinement prise en charge et le cours s'y tient, donc le premier ordre est : lis la documentation de la version 7.

Demande pour Claude Code

L'adresse de la base est un secret, donc le projet a besoin des règles deny pour .env vues dans la leçon 8_4. Si treasure-map n'en a pas encore, ajoute-les à .claude/settings.json en une phrase. Le changement touche les dépendances, le schéma, les données et plusieurs routes, donc tu commences par un plan :

Demande pour Claude Code :

/plan Déplace les tableaux de l'entrepôt sur globalThis vers une base
PostgreSQL via Prisma ORM en version 7, pas 8. Avant d'installer quoi
que ce soit, lis la documentation de Prisma 7 : le guide Next.js et la
page sur la base locale prisma dev. Installe toujours avec un numéro de
version. Modèles Pin, Board et PinOnBoard (un pin sur un tableau, couple
unique). Le seed reprend les pins de lib/pins.ts et les deux tableaux de
la leçon 13_2. lib/boards.ts lit la base, et canView et canSavePins ne
changent pas. L'adresse de la base vient seulement d'une variable
d'environnement ; tu ne lis pas .env, je collerai les adresses moi-même.
Crée la migration avec --create-only et attends que j'aie lu le SQL.
Ce sera fini quand les tests, le lint, npx tsc --noEmit et npm run build
passeront.

Dans le plan, vérifie deux choses : chaque commande d'installation est-elle accompagnée d'un numéro de version, et le plan s'arrête-t-il avant d'appliquer la migration ?

Ce que Claude a écrit : l'installation avec un numéro

Les premières commandes viennent du guide Prisma 7 pour Next.js. La documentation y écrit prisma@prev, ce qui aujourd'hui désigne la même version que prisma@7 :

npm install prisma@7 tsx @types/pg --save-dev
npm install @prisma/client@7 @prisma/adapter-pg dotenv pg
npx prisma --version

La première ligne installe l'outil en ligne de commande (CLI), la deuxième la bibliothèque de l'application avec l'adaptateur et le pilote pg. Chez nous, --version a affiché la version 7 pour les deux paquets. L'erreur typique de l'agent est npm install prisma sans numéro. Arrive alors le CLI en version 8 RC, qui, selon la documentation, ne lit pas schema.prisma et ne connaît ni generate ni migrate dev. Tu le reconnais avec npx prisma --version ou à "prisma": "^8.0.0-rc..." dans package.json. Un deuxième piège attend plus loin : le CLI en version 7 affiche un cadre "Update available" avec le conseil npm i --save-dev prisma@latest. Ce conseil, ni toi ni Claude ne le suivez.

Ce que Claude a écrit : la configuration

Claude a lancé npx prisma init --output ../app/generated/prisma --no-skills. --output est le chemin donné par le guide Next.js, et --no-skills évite l'installation des skills de Prisma pour les agents, que init téléchargerait depuis le réseau dans .claude/skills. Ont été créés prisma/schema.prisma, .env et un fichier de configuration :

// prisma7.config.ts
import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: { path: "prisma/migrations", seed: "tsx prisma/seed.ts" },
  datasource: {
    url: process.env["DATABASE_URL"],
    shadowDatabaseUrl: process.env["SHADOW_DATABASE_URL"],
  },
});

Le fichier s'appelle prisma7.config.ts : c'est le nom que Prisma lui donne depuis la version 7.10, même si beaucoup de pages de documentation écrivent encore prisma.config.ts. Prisma 7 ne charge pas .env tout seul, d'où import "dotenv/config" dès la première ligne. Les adresses ne viennent que de variables. La base fantôme (shadow database) est une seconde base de travail dans laquelle migrate dev rejoue les migrations pour vérifier qu'elles correspondent au schéma. Elle ne touche pas à tes données.

La base à bord : prisma dev

La base locale vient de Prisma elle-même : prisma dev lance PostgreSQL sur ton ordinateur, sans compte et sans Docker. Dans un deuxième onglet du terminal de Cursor, tape :

npx prisma dev --name treasure-map

Le nom sépare la base de ce projet de celles des autres. La documentation demande d'appuyer sur h et de copier deux adresses postgres:// dans .env. Tu les colles toi-même, car la règle deny interdit à Claude de lire ce fichier, et aussi d'y écrire :

# .env (recopie les ports depuis l'écran, chez toi ils seront différents)
DATABASE_URL="postgres://postgres:postgres@localhost:<port de la base>/template1?sslmode=disable"
SHADOW_DATABASE_URL="postgres://postgres:postgres@localhost:<port de la base fantôme>/template1?sslmode=disable"

L'adresse prisma+postgres:// écrite par init ne fonctionne pas avec l'adaptateur : chez nous, elle s'est terminée par Connection terminated unexpectedly. Sans la seconde adresse, la première migration passe et les suivantes échouent avec relation "..." already exists, ce que la documentation décrit et que nous avons vu avec "Pin".

Ce que Claude a écrit : le schéma

Ouvre prisma/schema.prisma. Le pin a reçu les mêmes champs que le type de la leçon 13_1, plus le propriétaire :

model Pin {
  id            String       @id @default(cuid())
  ownerId       String
  author        String
  title         String
  src           String
  width         Int
  height        Int
  dominantColor String
  tags          String[]
  createdAt     DateTime     @default(now())
  boards        PinOnBoard[]
}

@id @default(cuid()) désigne une clé primaire que la base remplit avec un texte aléatoire quand tu n'en donnes pas. String[] est une liste de textes que PostgreSQL range dans une seule colonne. Board a les champs de la leçon 13_2, sauf pinIds. À leur place, il reçoit le champ pins PinOnBoard[], c'est-à-dire ses lignes de la table de liaison décrite plus bas, et un @@index([ownerId]), car le profil cherche les tableaux par propriétaire. Les pins posés sur les tableaux sont décrits par un modèle à part :

model PinOnBoard {
  pinId   String
  boardId String
  savedAt DateTime @default(now())
  pin     Pin      @relation(fields: [pinId], references: [id], onDelete: Cascade)
  board   Board    @relation(fields: [boardId], references: [id], onDelete: Cascade)

  @@id([pinId, boardId])
}

C'est une table de liaison : une ligne, c'est un pin sur un tableau. @@id([pinId, boardId]) fait du couple une clé, donc le même pin n'entrera pas deux fois dans le même coffre. onDelete: Cascade supprime les lignes avec le tableau, mais les pins eux-mêmes restent.

La migration : d'abord tu lis

Claude a lancé npx prisma migrate dev --name init --create-only. Cet indicateur crée le fichier de migration mais ne l'applique pas. Ouvre dans Cursor prisma/migrations/<date>_init/migration.sql. Le passage le plus important :

CREATE TABLE "PinOnBoard" (
    "pinId" TEXT NOT NULL,
    "boardId" TEXT NOT NULL,
    "savedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    CONSTRAINT "PinOnBoard_pkey" PRIMARY KEY ("pinId","boardId")
);

Tu cherches trois choses : les tables attendues, la clé formée du couple et l'absence de DROP, car dans les migrations suivantes, DROP COLUMN efface des données. C'est toi qui lis, parce que /rewind annule les fichiers modifiés par les outils de Claude, pas le contenu de la base. Le prompt officiel de Prisma pour les agents demande aussi de s'arrêter et de poser la question quand migrate dev veut vider la base. Quand le SQL est conforme, tu réponds "applique", et Claude lance npx prisma migrate dev. Chez nous : Your database is now in sync with your schema.

generate et seed séparément

Dans Prisma 7, migrate dev ne génère plus le client et ne lance plus le seed, même si son aide dans le CLI le mentionne encore. Chez nous, le dossier app/generated n'existait pas après la migration. D'où deux commandes de plus :

npx prisma generate
npx prisma db seed

La première a signalé le client dans ./app/generated/prisma, et le seed a affiché Pins : 36, tableaux : 2. Le seed vide les tables et recopie les pins de lib/pins.ts ainsi que les deux tableaux d'identifiants b1 et b2, donc les commandes curl de la leçon 13_2 fonctionnent sans changement.

Ce que Claude a écrit : un seul client

Ouvre lib/prisma.ts :

// lib/prisma.ts
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "@/app/generated/prisma/client";

const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });

export const prisma = globalForPrisma.prisma ?? new PrismaClient({ adapter });
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

En mode développement, Next.js recharge les modules, et le client gardé sur globalThis survit au rechargement sans ouvrir de nouvelles connexions. L'import vient du dossier généré par generate, pas de @prisma/client. Sans adaptateur, Prisma 7 refuse : A driver adapter is required to connect to your database. dotenv n'est pas nécessaire ici, car Next.js charge .env lui-même.

Ce que Claude a écrit : les tableaux depuis la base

Dans lib/boards.ts, le type Board et les fonctions canView, canSavePins et boardCover sont restés mot pour mot. Seules les fonctions qui vont chercher les données ont changé :

// lib/boards.ts
export async function listBoards(ownerId: string, viewerId: string | null): Promise<Board[]> {
  const rows = await prisma.board.findMany({ where: { ownerId }, include: withPins, orderBy: { createdAt: "asc" } });
  return rows.map(toBoard).filter((board) => canView(board, viewerId));
}

include demande à Prisma de ramener, dans la même requête, les lignes liées. La constante withPins dit lesquelles : les seuls pinId de PinOnBoard, dans l'ordre d'enregistrement. toBoard transforme la ligne en la forme connue avec pinIds, donc les tests de la couverture de la leçon 13_2 sont passés sans changement. Le filtre canView reste dans le code de l'application : Prisma se connecte en propriétaire des tables et ne posera aucune serrure à ta place. Les fonctions sont désormais asynchrones, donc les pages et les routes ont reçu des await. L'enregistrement d'un pin sur un tableau est un upsert sur le couple pinId_boardId, c'est-à-dire "ajoute ou laisse tel quel".

La revue du capitaine

  1. Versions et adaptateur. Dans le diff de package.json, tu cherches "prisma": "^7 et "@prisma/client": "^7, et dans lib/prisma.ts le client avec { adapter } et l'adresse tirée de process.env.
  2. Le secret hors de Git. Dans Source Control, il n'y a pas de .env : la ligne .env* du .gitignore de create-next-app le cache, ce que montre git check-ignore -v .env.
  3. Le couple unique. @@id([pinId, boardId]) dans le schéma et PRIMARY KEY ("pinId","boardId") dans le SQL. Chez nous, deux POST /api/boards/b1/pins identiques ont donné deux fois 201 et une seule ligne, et un second create manuel s'est terminé par l'erreur P2002.
  4. Migration lue. Tu as ouvert dans Cursor chaque fichier de prisma/migrations avant que Claude l'applique. Ni /rewind ni git restore n'annuleront un changement de la base.

Pour finir, la preuve : crée un tableau avec le curl de la leçon 13_2, arrête le serveur et relance-le. Chez nous, "Cartes du marché" est revenu dans la liste. Le test de la leçon 13_2 a échoué deux fois à ce moment-là : d'abord parce que Vitest ne lit pas .env tout seul (Claude a ajouté loadEnv dans vitest.config.mts), ensuite à cause du nouveau tableau. Des tests sur une base partagée dépendent de son état, donc tu lances npx prisma db seed avant eux.

Étape suivante

Quand la revue passe, demande un commit "Tableaux et pins dans la base Prisma 7" et vérifie que .env n'est pas entré dans les changements. La page d'accueil et GET /api/pins lisent encore la liste de lib/pins.ts, et il n'y a aucun moyen d'ajouter un pin : c'est le travail de la leçon suivante. Après le travail, arrête la base : npx prisma dev stop treasure-map. Dans l'éditeur ci-dessous t'attend le registre en miniature : décoche des étapes, change la version et l'adresse, et regarde quel message apparaît en premier.

Retiens ceci : un trésor enterré dans le sable disparaît avec la marée, donc tu l'inscris dans le livre, et chaque page de ce livre, tu la lis avant d'y poser le sceau.

Code de cette leçon : App.tsx
// Le registre des trésors en miniature : les étapes de Prisma 7 et ce qui casse quand l'une manque
import { useState } from 'react';

type StepId = 'migrate' | 'generate' | 'seed' | 'adapter';

interface Step {
  id: StepId;
  command: string;
  what: string;
}

const STEPS: Step[] = [
  { id: 'migrate', command: 'npx prisma migrate dev', what: "les tables dans la base (SQL lu avant l'application)" },
  { id: 'generate', command: 'npx prisma generate', what: 'le client dans app/generated/prisma' },
  { id: 'seed', command: 'npx prisma db seed', what: 'les pins et les tableaux de départ' },
  { id: 'adapter', command: 'new PrismaClient({ adapter })', what: "le client avec l'adaptateur PrismaPg dans lib/prisma.ts" },
];

type Install = 'pinned' | 'unpinned';
type Address = 'postgres' | 'ppg';

interface RunResult {
  ok: boolean;
  lines: string[];
}

// La première erreur que tu vois en ouvrant /u/capitaine. Les messages viennent de vraies exécutions.
function openProfile(done: Record<StepId, boolean>, install: Install, address: Address): RunResult {
  if (install === 'unpinned') {
    return { ok: false, lines: ["npm install prisma (sans numéro) a apporté le CLI en version 8 RC.", 'npx prisma generate: No command registered for generate', 'Vérifie npx prisma --version et installe prisma@7.'] };
  }
  if (!done.generate) {
    return { ok: false, lines: ['Dans Prisma 7, migrate dev ne génère plus le client.', "Cannot find module '@/app/generated/prisma/client'", 'Lance npx prisma generate.'] };
  }
  if (!done.adapter) {
    return { ok: false, lines: ['PrismaClient was instantiated without any options.', 'A driver adapter is required to connect to your database.'] };
  }
  if (address === 'ppg') {
    return { ok: false, lines: ["L'adresse prisma+postgres:// de prisma init ne fonctionne pas avec PrismaPg.", 'Error: Connection terminated unexpectedly', "Colle dans .env l'adresse postgres:// de npx prisma dev."] };
  }
  if (!done.migrate) {
    return { ok: false, lines: ['P2021 The table public.Board does not exist in the current database.', "D'abord la migration : --create-only, lecture du SQL, puis migrate dev."] };
  }
  if (!done.seed) {
    return { ok: true, lines: ['La page fonctionne, mais le profil du capitaine est vide : 0 tableau.', "Dans Prisma 7, migrate dev ne lance pas le seed. Lance npx prisma db seed."] };
  }
  return { ok: true, lines: ['Tableaux : Îles à visiter (3 pins), Cachette du trésor (2 pins, secret).', 'Redémarre le serveur : les tableaux restent, car ils sont dans la base et non sur globalThis.'] };
}

function secondMigration(shadow: boolean): RunResult {
  return shadow
    ? { ok: true, lines: ['Applying migration ..._add_index', 'Your database is now in sync with your schema.'] }
    : { ok: false, lines: ['Sans SHADOW_DATABASE_URL, la première migration passe, les suivantes non :', 'ERROR: relation "Pin" already exists'] };
}

export default function App() {
  const [done, setDone] = useState<Record<StepId, boolean>>({ migrate: true, generate: false, seed: false, adapter: true });
  const [install, setInstall] = useState<Install>('pinned');
  const [address, setAddress] = useState<Address>('postgres');
  const [shadow, setShadow] = useState(true);
  const [result, setResult] = useState<RunResult | null>(null);

  return (
    <div className="min-h-screen space-y-4 bg-amber-50 p-4 text-zinc-900">
      <h1 className="text-xl font-bold">Le registre des trésors : l'ordre de Prisma 7</h1>
      <div className="flex flex-wrap gap-3 text-sm">
        <label className="flex items-center gap-2">
          Installation :
          <select value={install} onChange={(e) => setInstall(e.target.value as Install)} className="rounded border border-zinc-300 px-2 py-1">
            <option value="pinned">prisma@7 et @prisma/client@7</option>
            <option value="unpinned">prisma sans numéro de version</option>
          </select>
        </label>
        <label className="flex items-center gap-2">
          Adresse dans .env :
          <select value={address} onChange={(e) => setAddress(e.target.value as Address)} className="rounded border border-zinc-300 px-2 py-1">
            <option value="postgres">postgres:// de prisma dev</option>
            <option value="ppg">prisma+postgres:// de prisma init</option>
          </select>
        </label>
      </div>
      <ol className="space-y-2">
        {STEPS.map((step) => (
          <li key={step.id} className="rounded-xl bg-white p-2">
            <label className="flex items-center gap-2">
              <input type="checkbox" checked={done[step.id]} onChange={(e) => setDone({ ...done, [step.id]: e.target.checked })} />
              <code className="font-semibold">{step.command}</code>
            </label>
            <p className="ml-6 text-sm text-zinc-600">{step.what}</p>
          </li>
        ))}
      </ol>
      <div className="flex flex-wrap items-center gap-2">
        <button type="button" onClick={() => setResult(openProfile(done, install, address))} className="rounded-full bg-red-600 px-4 py-2 font-semibold text-white">
          Ouvrir /u/capitaine
        </button>
        <button type="button" onClick={() => setResult(secondMigration(shadow))} className="rounded-full bg-zinc-200 px-4 py-2">
          Deuxième migration
        </button>
        <label className="flex items-center gap-2 text-sm">
          <input type="checkbox" checked={shadow} onChange={(e) => setShadow(e.target.checked)} />
          SHADOW_DATABASE_URL dans .env
        </label>
      </div>
      {result && (
        <ul role="status" className={result.ok ? 'space-y-1 rounded-xl bg-emerald-100 p-3 font-mono text-sm' : 'space-y-1 rounded-xl bg-red-100 p-3 font-mono text-sm'}>
          {result.lines.map((line) => (
            <li key={line}>{line}</li>
          ))}
        </ul>
      )}
      <p className="text-sm text-zinc-600">Décoche une étape à la fois et regarde quel message apparaît en premier.</p>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Qu'est-ce que Prisma ORM dans Treasure Map ?

  2. 2. Comment récupérer, avec un seul appel à findMany, les tableaux avec leurs lignes de la table de liaison PinOnBoard ?

Tâches pratiques dans le jeu

  • Clique dans l'ordre

    Clique sur les éléments pour construire l'expression de lib/prisma.ts qui crée le client Prisma 7 (un élément est en trop) :

  • Éditeur de code

    Crée un modèle et des requêtes Prisma

  • Tri vertical

    Ordonne les étapes par lesquelles les tableaux de Treasure Map sont arrivés dans la base avec Prisma 7 :

  1. QuestionQuiz : qu'est-ce que Prisma
  2. Clique dans l'ordreConstruction : le client avec adaptateur
  3. Exercice de codePratique : Prisma
  4. Remets dans l'ordreTri : l'ordre de travail avec Prisma 7
  5. QuestionQuiz : les relations dans Prisma

Articles utiles