Kurs vibe coding z Claude Code · Moduł 14: Klon Pinteresta
Rejestr skarbów: baza danych dla pinów i tablic
W tej lekcji13
Załóż tablicę "Mapy z targu" a potem zatrzymaj serwer i uruchom go jeszcze raz. Tablicy nie ma. Skrzynie z lekcji 13_2 leżą w magazynie na globalThis, czyli w pamięci jednego procesu Node, a piny w liście w lib/pins.ts. Każdy restart zaczyna od zera, a potrzebna jest księga portowa, która przetrwa sztorm: baza danych. Do rozmowy z nią Claude użyje Prisma ORM. ORM to biblioteka, która zamienia wiersze tabel na obiekty TypeScriptu, więc zamiast pisać SQL ręcznie wołasz prisma.board.findMany() i dostajesz typy.
Czego się nauczysz
- kazać Claude przeczytać dokumentację właściwej wersji, zanim cokolwiek zainstaluje, i rozpoznać pułapkę wersji;
- uruchomić lokalną bazę bez konta i bez Dockera i wpisać jej adres tak, żeby agent go nie widział;
- przeczytać migrację SQL, zanim dotknie bazy;
- przenieść tablice do bazy tak, żeby zasady dostępu z lekcji 13_2 zostały bez zmian.
Cztery słowa przed rejsem
Schemat (prisma/schema.prisma) opisuje tabele w języku Prismy. Migracja to plik SQL, który zmienia bazę z wczoraj w bazę z dzisiaj, i trafia do repozytorium. Klient to kod TypeScriptu wygenerowany ze schematu, z metodą dla każdej tabeli. Adapter to sterownik, przez który klient łączy się z PostgreSQL.
Haczyk z kalendarza, stan na listopad 2026: npm pod tagiem latest daje Prisma ORM 8, wciąż wersję kandydującą (release candidate). Prisma 7 jest w pełni wspierana i kurs zostaje przy niej, więc pierwszy rozkaz brzmi: przeczytaj dokumentację wersji 7.
Polecenie dla Claude Code
Adres bazy to sekret, więc projekt potrzebuje reguł deny dla .env z lekcji 8_4. Jeśli treasure-map jeszcze ich nie ma, przenieś je do .claude/settings.json jednym zdaniem. Zmiana dotyka zależności, schematu, danych i kilku tras, więc zaczynasz od planu:
Polecenie dla Claude Code:
/plan Przenieś tablice z magazynu na globalThis do bazy PostgreSQL
przez Prisma ORM w wersji 7, nie 8. Zanim cokolwiek zainstalujesz,
przeczytaj dokumentację Prisma 7: przewodnik Next.js i stronę o lokalnej
bazie prisma dev. Instaluj zawsze z numerem wersji. Modele Pin, Board
i PinOnBoard (pin na tablicy, para unikalna). Seed przenosi piny
z lib/pins.ts i obie tablice z lekcji 13_2. lib/boards.ts czyta bazę,
a canView i canSavePins zostają bez zmian. Adres bazy tylko ze zmiennej
środowiskowej; .env nie czytasz, adresy wkleję sam. Migrację twórz
z --create-only i czekaj, aż przeczytam SQL. Gotowe, gdy testy, lint,
npx tsc --noEmit i npm run build przejdą.W planie sprawdź dwie rzeczy: czy przy każdej komendzie instalacji stoi numer wersji i czy plan zatrzymuje się przed zastosowaniem migracji.
Co napisał Claude: instalacja z numerem
Pierwsze komendy pochodzą z przewodnika Prisma 7 dla Next.js. Dokumentacja pisze tam prisma@prev, co dziś oznacza tę samą wersję co prisma@7:
npm install prisma@7 tsx @types/pg --save-dev
npm install @prisma/client@7 @prisma/adapter-pg dotenv pg
npx prisma --versionPierwsza linia instaluje narzędzie wiersza poleceń (CLI), druga bibliotekę aplikacji z adapterem i sterownikiem pg. U nas --version pokazała przy obu paczkach wersję 7. Typowy błąd agenta to npm install prisma bez numeru. Przychodzi wtedy CLI w wersji 8 RC, które według dokumentacji nie czyta schema.prisma i nie zna generate ani migrate dev. Rozpoznasz to po npx prisma --version albo po "prisma": "^8.0.0-rc..." w package.json. Druga pułapka czeka później: CLI w wersji 7 pokazuje ramkę "Update available" z radą npm i --save-dev prisma@latest. Tej rady nie słuchasz ani Ty, ani Claude.
Co napisał Claude: konfiguracja
Claude uruchomił npx prisma init --output ../app/generated/prisma --no-skills. --output to ścieżka z przewodnika Next.js, a --no-skills pomija instalację skilli Prismy dla agentów, które init pobrałby z sieci do .claude/skills. Powstały prisma/schema.prisma, .env i plik konfiguracji:
// 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"],
},
});Nazwa pliku to prisma7.config.ts: tak nazywa go Prisma od wersji 7.10, choć wiele stron dokumentacji wciąż pisze prisma.config.ts. Prisma 7 nie wczytuje .env sama, stąd import "dotenv/config" w pierwszej linii. Adresy przychodzą tylko ze zmiennych. Baza cienia (shadow database) to druga, robocza baza, w której migrate dev odtwarza migracje, żeby sprawdzić, czy zgadzają się ze schematem. Twoich danych nie dotyka.
Baza na pokładzie: prisma dev
Lokalną bazę daje sama Prisma: prisma dev uruchamia PostgreSQL na Twoim komputerze, bez konta i bez Dockera. W drugiej karcie terminala w Cursorze wpisz:
npx prisma dev --name treasure-mapNazwa oddziela bazę tego projektu od innych. Dokumentacja każe nacisnąć h i skopiować dwa adresy postgres:// do .env. Wklejasz je sam, bo reguła deny blokuje Claude odczyt tego pliku, a także jego zapis:
# .env (porty przepisz z ekranu, u Ciebie będą inne)
DATABASE_URL="postgres://postgres:postgres@localhost:<port bazy>/template1?sslmode=disable"
SHADOW_DATABASE_URL="postgres://postgres:postgres@localhost:<port cienia>/template1?sslmode=disable"Adres prisma+postgres://, który wpisał init, nie działa z adapterem: u nas skończył się Connection terminated unexpectedly. Bez drugiego adresu pierwsza migracja przechodzi, a kolejne padają z relation "..." already exists, co dokumentacja opisuje, a my zobaczyliśmy przy "Pin".
Co napisał Claude: schemat
Otwórz prisma/schema.prisma. Pin dostał te same pola co typ z lekcji 13_1 i właściciela:
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()) oznacza klucz główny, który baza wypełni losowym napisem, gdy go nie podasz. String[] to lista napisów, którą PostgreSQL trzyma w jednej kolumnie. Board ma pola z lekcji 13_2 poza pinIds. W ich miejsce dostaje pole pins PinOnBoard[], czyli swoje wpisy z tabeli łączącej opisanej niżej, a do tego @@index([ownerId]), bo profil szuka tablic po właścicielu. Piny na tablicach opisuje osobny model:
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])
}To tabela łącząca: jeden wiersz to jeden pin na jednej tablicy. @@id([pinId, boardId]) robi z pary klucz, więc ten sam pin nie trafi dwa razy do tej samej skrzyni. onDelete: Cascade usuwa wpisy razem z tablicą, ale same piny zostają.
Migracja: najpierw czytasz
Claude uruchomił npx prisma migrate dev --name init --create-only. Ta flaga tworzy plik migracji, ale go nie stosuje. Otwórz w Cursorze prisma/migrations/<data>_init/migration.sql. Najważniejszy fragment:
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")
);Szukasz trzech rzeczy: oczekiwanych tabel, klucza z pary i braku DROP, bo w kolejnych migracjach DROP COLUMN kasuje dane. Czytasz Ty, bo /rewind cofa pliki zmieniane narzędziami Claude, a nie zawartość bazy. Oficjalny prompt Prismy dla agentów każe też zatrzymać się i zapytać, gdy migrate dev chce wyczyścić bazę. Gdy SQL się zgadza, odpowiadasz "stosuj", a Claude uruchamia npx prisma migrate dev. U nas: Your database is now in sync with your schema.
generate i seed osobno
W Prisma 7 migrate dev nie generuje już klienta ani nie uruchamia seeda, choć jego pomoc w CLI wciąż o tym wspomina. U nas po migracji folderu app/generated nie było. Dlatego dwie kolejne komendy:
npx prisma generate
npx prisma db seedPierwsza zgłosiła klienta w ./app/generated/prisma, a seed wypisał Piny: 36, tablice: 2. Seed czyści tabele i przepisuje piny z lib/pins.ts oraz obie tablice z identyfikatorami b1 i b2, więc polecenia curl z lekcji 13_2 działają bez zmian.
Co napisał Claude: jeden klient
Otwórz 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;W trybie deweloperskim Next.js ładuje moduły od nowa, a klient zapamiętany na globalThis przetrwa przeładowanie bez nowych połączeń. Import idzie z folderu wygenerowanego przez generate, a nie z @prisma/client. Bez adaptera Prisma 7 odmawia: A driver adapter is required to connect to your database. dotenv nie jest tu potrzebny, bo Next.js sam wczytuje .env.
Co napisał Claude: tablice z bazy
W lib/boards.ts typ Board i funkcje canView, canSavePins, boardCover zostały słowo w słowo. Zmieniły się tylko funkcje, które sięgają po dane:
// 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 każe Prismie dociągnąć w tym samym zapytaniu powiązane wiersze. Stała withPins mówi które: same pinId z PinOnBoard, w kolejności zapisywania. toBoard zamienia wiersz na znany kształt z pinIds, więc testy okładki z lekcji 13_2 przeszły bez zmian. Filtr canView dalej stoi w kodzie aplikacji: Prisma łączy się jako właściciel tabel i żadnego zamka za Ciebie nie założy. Funkcje są teraz asynchroniczne, więc strony i trasy dostały await. Zapis pinu na tablicy to upsert po parze pinId_boardId, czyli "dodaj albo zostaw".
Przegląd kapitana
- Wersje i adapter. W diffie
package.jsonszukasz"prisma": "^7i"@prisma/client": "^7, a wlib/prisma.tsklienta z{ adapter }i adresem zprocess.env. - Sekret poza Gitem. W Source Control nie ma
.env: ukrywa go linia.env*z.gitignoreodcreate-next-app, co pokażegit check-ignore -v .env. - Para unikalna.
@@id([pinId, boardId])w schemacie iPRIMARY KEY ("pinId","boardId")w SQL. U nas dwa takie samePOST /api/boards/b1/pinsdały dwa razy 201 i jeden wiersz, a ręczny drugicreateskończył się błędemP2002. - Migracja przeczytana. Każdy plik w
prisma/migrationsotworzyłeś w Cursorze, zanim Claude go zastosował. Zmiany w bazie nie cofnie ani/rewind, anigit restore.
Na koniec dowód: załóż tablicę przez curl z lekcji 13_2, zatrzymaj serwer i uruchom go znowu. U nas "Mapy z targu" wróciły na listę. Test z lekcji 13_2 padł przy tym dwa razy: najpierw dlatego, że Vitest nie czyta .env sam (Claude dopisał loadEnv w vitest.config.mts), potem przez nową tablicę. Testy na wspólnej bazie zależą od jej stanu, więc przed nimi uruchamiasz npx prisma db seed.
Następny krok
Gdy przegląd przejdzie, poproś o commit "Tablice i piny w bazie Prisma 7" i sprawdź, że .env nie wszedł do zmian. Strona główna i GET /api/pins czytają jeszcze listę z lib/pins.ts, a dodać pinu nie ma jak: to zadanie następnej lekcji. Po pracy zatrzymaj bazę: npx prisma dev stop treasure-map. W edytorze poniżej czeka rejestr w miniaturze: odznaczaj kroki, zmieniaj wersję i adres, i patrz, który komunikat pojawi się pierwszy.
Zapamiętaj: skarb zakopany w piasku znika z przypływem, więc zapisujesz go w księdze, a każdą stronę tej księgi czytasz, zanim przyłożysz pieczęć.
Kod do tej lekcji: App.tsx
// Rejestr skarbów w miniaturze: kroki Prisma 7 i to, co pęka, gdy któregoś brakuje
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: 'tabele w bazie (SQL przeczytany przed zastosowaniem)' },
{ id: 'generate', command: 'npx prisma generate', what: 'klient w app/generated/prisma' },
{ id: 'seed', command: 'npx prisma db seed', what: 'piny i tablice startowe' },
{ id: 'adapter', command: 'new PrismaClient({ adapter })', what: 'klient z adapterem PrismaPg w lib/prisma.ts' },
];
type Install = 'pinned' | 'unpinned';
type Address = 'postgres' | 'ppg';
interface RunResult {
ok: boolean;
lines: string[];
}
// Pierwszy błąd, który zobaczysz po otwarciu /u/kapitan. Komunikaty pochodzą z prawdziwych uruchomień.
function openProfile(done: Record<StepId, boolean>, install: Install, address: Address): RunResult {
if (install === 'unpinned') {
return { ok: false, lines: ['npm install prisma (bez numeru) przyniósł CLI w wersji 8 RC.', 'npx prisma generate: No command registered for generate', 'Sprawdź npx prisma --version i zainstaluj prisma@7.'] };
}
if (!done.generate) {
return { ok: false, lines: ['migrate dev w Prisma 7 nie generuje już klienta.', "Cannot find module '@/app/generated/prisma/client'", 'Uruchom 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: ['Adres prisma+postgres:// z prisma init nie działa z PrismaPg.', 'Error: Connection terminated unexpectedly', 'Wklej do .env adres postgres:// z npx prisma dev.'] };
}
if (!done.migrate) {
return { ok: false, lines: ['P2021 The table public.Board does not exist in the current database.', 'Najpierw migracja: --create-only, lektura SQL, potem migrate dev.'] };
}
if (!done.seed) {
return { ok: true, lines: ['Strona działa, ale profil kapitana jest pusty: 0 tablic.', 'migrate dev w Prisma 7 nie uruchamia seeda. Uruchom npx prisma db seed.'] };
}
return { ok: true, lines: ['Tablice: Wyspy do odwiedzenia (3 piny), Kryjówka skarbu (2 piny, tajna).', 'Zrestartuj serwer: tablice zostają, bo leżą w bazie, a nie na 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: ['Bez SHADOW_DATABASE_URL pierwsza migracja przechodzi, kolejne nie:', '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">Rejestr skarbów: kolejność Prisma 7</h1>
<div className="flex flex-wrap gap-3 text-sm">
<label className="flex items-center gap-2">
Instalacja:
<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 i @prisma/client@7</option>
<option value="unpinned">prisma bez numeru wersji</option>
</select>
</label>
<label className="flex items-center gap-2">
Adres w .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:// z prisma dev</option>
<option value="ppg">prisma+postgres:// z 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">
Otwórz /u/kapitan
</button>
<button type="button" onClick={() => setResult(secondMigration(shadow))} className="rounded-full bg-zinc-200 px-4 py-2">
Druga migracja
</button>
<label className="flex items-center gap-2 text-sm">
<input type="checkbox" checked={shadow} onChange={(e) => setShadow(e.target.checked)} />
SHADOW_DATABASE_URL w .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">Odznacz jeden krok naraz i sprawdź, który komunikat pojawi się pierwszy.</p>
</div>
);
}Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Czym jest Prisma ORM w Treasure Map?
2. Jak jednym wywołaniem findMany pobrać tablice razem z ich wpisami z tabeli łączącej PinOnBoard?
Zadania praktyczne w grze
- Klikanie w kolejności
Kliknij elementy, aby zbudować wyrażenie z lib/prisma.ts, które tworzy klienta Prisma 7 (jeden element jest zbędny):
- Edytor kodu
Stwórz model i zapytania Prisma
- Układanie w pionie
Uporządkuj kroki, którymi tablice Treasure Map trafiły do bazy w Prisma 7: