Praca z bazą danych w Claude Code: schematy, migracje, zapytania i dane testowe

Poziom 2 Poradnik Zaktualizowano 2026-10-12

Claude Code pracuje z bazą danych, czytając pliki schematu, historię migracji i modele ORM projektu, a następnie przygotowuje zmiany schematu, pliki migracji, zapytania i skrypty seedujące zgodne z tymi konwencjami. Najważniejsze zastrzeżenie: Claude Code pisze pliki i sprawdza je na jednorazowej bazie, a migracje na współdzielonych środowiskach stosuje pipeline CI, nie agent.

Ta strona jest dla programistów, którzy używają Claude Code w terminalu i chcą dopuścić go do danych. Nowa funkcja potrzebuje trzech tabel, zapytanie raportowe trwa osiem sekund, a testy nie mają realistycznych danych. Claude Code przygotuje to wszystko w kilka minut. Ryzyko leży w kolejnym kroku: migracja, która blokuje tabelę z 20 milionami wierszy, albo agent, którego powłoka zna produkcyjny connection string.

Co zyskasz, pracując z bazą danych w Claude Code

Konfigurację sesji, w której Claude Code może zmieniać pliki schematu, ale nie sięga do współdzielonej bazy.
Prompty do skopiowania: projekt schematu, plik migracji, wolne zapytanie, zapytanie ORM, dane seedowe i mapa użycia tabel przygotowana przez subagenty.
Test na jednorazowej bazie (up, down, up, diff schematu), który dowodzi poprawności migracji bez czytania każdej linii SQL.
Bezobsługowy audyt claude -p, który zwraca JSON gotowy do użycia w jobie CI.
Typowe awarie przy pracy z bazą i sposób wyjścia z każdej z nich.

Ustal granice przed pierwszym promptem

Błędy w bazie danych są drogie, bo dotyczą współdzielonego stanu. Trzy ustawienia trzymają Claude Code po bezpiecznej stronie tej granicy, a kolejność ma znaczenie: najpierw poświadczenia, potem reguły, na końcu kontekst.

Nie dawaj powłoce Claude Code poświadczeń do współdzielonych baz

Claude Code uruchamia polecenia z twoim środowiskiem. W Claude Code v2.1.283 lub nowszym (oba kanały wydań na 2026-10-12) tryb auto jest startowym trybem uprawnień w interaktywnych sesjach terminalowych na obsługiwanych przez niego modelach, więc większość poleceń zatwierdza klasyfikator, a nie ty. Jeśli DATABASE_URL w tej powłoce wskazuje staging albo produkcję, jedno migrate deploy do niej dotrze. Jeśli nie masz jeszcze Claude Code, zacznij od instalacji; o tym, jak tryby uprawnień i sandboxing ograniczają sesję, przeczytasz na stronie uprawnienia i sandboxing.

Uruchamiaj Claude Code w powłoce, w której DATABASE_URL wskazuje lokalną albo jednorazową bazę. Wystarczy tymczasowy kontener Postgresa:

# Terminal: bazy roboczej można się pozbyć w każdej chwili
docker run --rm -d --name pg-scratch -e POSTGRES_PASSWORD=scratch -p 55432:5432 postgres:17
export DATABASE_URL="postgresql://postgres:scratch@localhost:55432/postgres"
claude

Jeśli agent musi czytać staging, daj mu rolę tylko do odczytu przez serwer MCP, a nie connection string w powłoce. Strona serwery MCP dla baz danych opisuje tę rolę oraz instalację Postgres MCP Pro, DBHub, Supabase, Neon i MongoDB. Dla Postgres MCP Pro w Claude Code wpis na poziomie projektu wygląda tak:

# Terminal, katalog główny repo: zapisuje .mcp.json; ${STAGING_DATABASE_URL} jest rozwijane z powłoki przy starcie
claude mcp add -s project postgres -e 'DATABASE_URI=${STAGING_DATABASE_URL}' \
  -- uvx postgres-mcp --access-mode=restricted

--access-mode=restricted wykonuje zapytania w transakcjach tylko do odczytu z limitami czasu wykonania. Mimo to ustaw STAGING_DATABASE_URL na rolę tylko do odczytu, żeby ograniczenie egzekwowała baza, a nie tylko serwer. Postgres MCP Pro to pakiet z PyPI uruchamiany przez uvx; pakiet npm o nazwie postgres-mcp nie ma z nim nic wspólnego. Ostatnie wydanie na PyPI to 0.3.0 z 2025-05-16 (stan na 2026-09-26), więc zanim zespół się na nim oprze, sprawdź, czy projekt jest nadal rozwijany.

Zablokuj polecenia, które zapisują do współdzielonych baz

Dodaj reguły deny do .claude/settings.json, żeby najczęstsze warianty polecenia „zastosuj tę migrację” nigdy nie zostały uruchomione w sesji. Dopasuj listę do swojego narzędzia migracji:

{
  "permissions": {
    "deny": [
      "Bash(npx prisma migrate deploy *)",
      "Bash(npx prisma db push *)",
      "Bash(npx drizzle-kit push *)",
      "Bash(npx drizzle-kit migrate *)"
    ],
    "ask": [
      "Bash(npx prisma migrate reset *)"
    ]
  }
}

Powiedz Claude Code, gdzie w repo mieszka baza

Zapisz konwencje bazodanowe w CLAUDE.md, żeby każda sesja zaczynała się od nich. Gdzie umieścić plik, opisuje system pamięci.

## Database
- Schema: prisma/schema.prisma. Migrations: prisma/migrations/ (never edit an applied one).
- Create a migration file only: `npx prisma migrate dev --create-only --name <change>`.
- The only database you may touch is $DATABASE_URL (local scratch). Never run `migrate deploy`.
- IDs are UUIDv7 strings, timestamps are `timestamptz` named created_at / updated_at.
- Every migration ships with a tested down path or a written reason why it is irreversible.

Projektuj schemat w trybie planowania

Tryb planowania pozwala Claude Code przeczytać schemat i zaproponować projekt bez edytowania czegokolwiek. Naciskaj Shift+Tab, aż wskaźnik pokaże tryb planowania, albo uruchom claude --permission-mode plan. Poproś o projekt i o zapytania, które ma obsługiwać, w jednym prompcie, bo indeksy wynikają z zapytań.

Read prisma/schema.prisma and the last five migrations in prisma/migrations/ to learn our conventions (ID type, naming, timestamps, soft deletes).

Design the schema for a teams feature:
- teams: name, unique slug, billing email
- team_memberships: user, team, role (owner, admin, member); a user can belong to many teams; exactly one owner per team
- team_invitations: email, role, token, expires 7 days after creation; one open invitation per (team, email)

List the five queries the app will run most often against these tables, then derive the indexes from them.
For every foreign key, state the ON DELETE behaviour and why.
Say which constraint enforces "exactly one owner per team" in the database, or say plainly that it cannot and where the application must enforce it.
Show the schema diff only. Do not write a migration yet.

Zanim zatwierdzisz plan, sprawdź go według tej tabeli. Każdy wiersz kosztuje teraz niewiele, a po uruchomieniu migracji dużo.

Sprawdzenie	Jak wygląda zła odpowiedź
Zgodność z konwencjami	`id serial` w schemacie, który wszędzie indziej używa UUID jako tekstu
Zachowanie przy usuwaniu	`ON DELETE CASCADE` z users do teams, które usuwa zespół, gdy odchodzi jego właściciel
Niezmienniki w bazie	„dokładnie jeden właściciel” pilnowany tylko w kodzie aplikacji, bez częściowego indeksu unikalnego
Indeksy wynikają z zapytań	indeks na każdym kluczu obcym i żadnego na najczęstszym wyszukiwaniu `(team_id, role)`

Wygeneruj plik migracji i sprawdź go na jednorazowej bazie

Claude Code pisze migrację. Nie stosuje jej nigdzie poza bazą roboczą. Wzorce bez przestojów, takie jak expand-contract, backfill w partiach i budowa indeksów online, szczegółowo opisuje strona migracje baz danych i kodu. Ta sekcja dotyczy pętli, którą przechodzisz przy każdej migracji.

Utwórz plik, nie stosując go. Użyj polecenia create-only swojego narzędzia: npx prisma migrate dev --create-only --name add_teams dla Prismy albo npx drizzle-kit generate dla Drizzle. Potem poproś Claude Code o przejrzenie i uzupełnienie wygenerowanego SQL.

Open the newest migration in prisma/migrations/. It was generated from the schema change we agreed.

For each statement, add a SQL comment that answers: does it take a lock that blocks writes, for roughly how long on a table of the size in the comment at the top of the file, and is it reversible?
Rewrite any statement that blocks writes on an existing table: add NOT NULL columns as nullable first, build indexes on existing tables with CREATE INDEX CONCURRENTLY in a migration of their own (it cannot run inside a transaction block), and add foreign keys with NOT VALID followed by VALIDATE CONSTRAINT.
Write the down migration in a file named down.sql next to it. If a step cannot be undone without data loss, say so at the top of down.sql instead of pretending.
Do not run anything against any database.

Przepuść ją przez linter. Squawk wykrywa blokujące instrukcje w migracjach Postgresa. Uruchom npx -y squawk-cli prisma/migrations/*/migration.sql (squawk-cli 2.66.0 według npm z 2026-09-26) i wklej każde znalezisko z powrotem do Claude Code.
Wykonaj up, down, up na bazie roboczej i porównaj schematy. To dowód, że działa zarówno migracja, jak i jej wycofanie. Zwykły psql nie zapisuje nic w tabeli historii migracji narzędzia, więc ta tabela nie zaburza porównania. Pętla zakłada, że baza robocza ma już zastosowane wszystkie migracje sprzed add_teams, czyli stan, w jakim zostawia ją uruchomienie Prismy z --create-only. Ani create-only w Prismie, ani drizzle-kit generate (drizzle-kit 0.31.11 nie ma migracji down) nie tworzy down.sql; pisze go Claude Code na podstawie promptu z kroku 1. W Drizzle wygenerowany plik leży w drizzle/<numer>_<nazwa>.sql, a nie w osobnym katalogu, więc ustaw M i obie ścieżki plików na niego i na napisany ręcznie plik down.
Okno terminala
```
# Terminal albo sesja Claude Code: dotyka tylko bazy roboczej
M=$(ls -d prisma/migrations/*_add_teams)
pg_dump --schema-only "$DATABASE_URL" > /tmp/schema-before.sql
psql -v ON_ERROR_STOP=1 "$DATABASE_URL" -f "$M/migration.sql"
psql -v ON_ERROR_STOP=1 "$DATABASE_URL" -f "$M/down.sql"
pg_dump --schema-only "$DATABASE_URL" > /tmp/schema-after-down.sql
diff /tmp/schema-before.sql /tmp/schema-after-down.sql && echo "down path restores the schema"
psql -v ON_ERROR_STOP=1 "$DATABASE_URL" -f "$M/migration.sql"
```
Claude Code może przejść tę pętlę sam, bo jedyna baza w jego powłoce to baza robocza. Pusty diff i czyste drugie zastosowanie migracji to dowód, którego potrzebujesz. Nie musisz czytać SQL linijka po linijce, żeby mu zaufać.
Otwórz pull request z dowodami. Wynik lintera, diff schematu i przebieg testów trafiają do opisu. CI powtarza test up-down-up na świeżej bazie, a właściciel schematu zatwierdza zmianę. Po merge’u migrację stosuje pipeline. Zobacz wdrożenie.

Pisz i strój zapytania na prawdziwych planach

Claude Code częściej pisze poprawny SQL, gdy widzi plan zapytania, zamiast go zgadywać. Daj mu zapytanie, wynik EXPLAIN i dostęp do schematu, a potem poproś o mierzalny wynik.

This query takes about 8 seconds on staging. The plan below is from EXPLAIN (ANALYZE, BUFFERS) run as the read-only role.

<paste the query>
<paste the plan>

Read our schema and the existing indexes for every table in the query.
1. Name the plan node that costs the most time and explain why the planner chose it (row estimate vs actual, missing index, sort spilling to disk).
2. Propose at most two fixes, ranked: a query rewrite, an index, or a code change that stops sending this query.
3. For an index, give the CREATE INDEX CONCURRENTLY statement and name the write-heavy tables it slows down.
4. Rewrite the query if that helps, and give me a psql command I can run on the scratch database to compare both versions with EXPLAIN (ANALYZE).

Kod ORM ukrywa SQL, a w ukrytym SQL mieszkają pętle N+1 i nieograniczone include. Poproś zarówno o kod ORM, jak i o SQL, który on generuje, a kryterium akceptacji niech będzie test.

Read src/db/schema.ts (Drizzle). Write a function listRecentOrders(customerId, cursor) that returns completed or shipped orders from the last 30 days, with customer name and email and each order's items with product names, sorted by total descending, paginated with a cursor, 50 per page.

Use the relational query API. Log the SQL it generates and show it to me.
If the SQL issues more than one query per page, explain why and fix it.
Write a Vitest test that seeds two customers with orders on both sides of the 30-day boundary and asserts the exact IDs returned on page 1 and page 2.
Run the test against $DATABASE_URL and show me the result.

Generuj realistyczne dane seedowe i fabryki testowe

Skrypty seedujące psują się na dwa przewidywalne sposoby: wstawiają wiersze w złej kolejności zależności i tworzą duplikaty przy drugim uruchomieniu. Zapisz oba ograniczenia w prompcie.

Read the schema and scripts/seed.ts. Extend the seed to create:
- 50 users, 10 teams with 3-15 members each (one owner per team)
- 200 products in 5 categories
- 500 orders over the last 6 months, weighted toward the most recent month, fewer on weekends
- reviews for about 60% of products, mostly 4-5 stars

Insert in foreign-key order and use the IDs returned by earlier inserts, never hardcoded ones.
Make it idempotent: upsert on natural keys (email, slug, SKU) so a second run changes nothing.
Use a fixed random seed so every run produces the same data.
Run it twice against $DATABASE_URL and show me row counts after each run. They must match.

Do testów poproś o fabryki zgodne z tests/fixtures/ (createTestUser(overrides?), createTestTeam(owner, overrides?)) i o owinięcie każdego testu transakcją, która się wycofuje. Fabryki trzymają dane testu obok jego asercji, więc test da się zrozumieć bez zaglądania do pliku seedów. Strategię testowania w ogóle opisuje strona o testowaniu.

Zmapuj użycie bazy subagentami przed ryzykowną zmianą

Zanim zmienisz nazwę kolumny albo podzielisz tabelę, znajdź każde miejsce, które od niej zależy. Subagenty przeszukują kod równolegle i zwracają podsumowania, więc główna sesja zachowuje kontekst na samą zmianę.

We plan to split users.name into first_name and last_name. Use three Explore subagents in parallel:
1. Find every read and write of users.name: ORM calls, raw SQL, views, triggers, seed files, fixtures and analytics exports. List file and line, grouped by read or write.
2. Find every raw SQL string built from user input anywhere in the codebase and flag any that is not parameterized.
3. Read prisma/migrations/ and list every past migration that dropped or rewrote data, and whether it had a down path.
Merge the results into one table and propose the order of changes (expand, dual write, backfill, switch reads, contract). Do not edit any file.

Jeśli chcesz mieć specjalistę od bazy na stałe, zdefiniuj go raz w .claude/agents/. Opisuje to strona własne subagenty.

Uruchamiaj audyty bazy bezobsługowo przez `claude -p`

Audyt uruchamiany z harmonogramu albo dla każdego pull requesta nie potrzebuje człowieka przy klawiaturze. claude -p wykonuje jeden prompt i kończy działanie. Ogranicz go do narzędzi tylko do odczytu flagą --tools i poproś o ustrukturyzowany wynik przez --json-schema, żeby skrypt odczytał znaleziska z pola structured_output.

# CI albo terminal: audyt schematu tylko do odczytu, wynik czytelny dla maszyny
claude -p "Read prisma/schema.prisma and prisma/migrations/. Report: tables without a primary key, \
foreign keys without a supporting index, nullable columns that every write path sets, \
and naming that breaks the conventions in CLAUDE.md. One finding per issue." \
  --tools "Read,Grep,Glob" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"table":{"type":"string"},"column":{"type":"string"},"issue":{"type":"string"},"fix":{"type":"string"}},"required":["table","issue","fix"]}}},"required":["findings"]}' \
  | jq '.structured_output.findings'

--tools określa, które wbudowane narzędzia w ogóle istnieją w przebiegu, więc audyt nie ma do dyspozycji Bash, Edit ani Write. To mocniejsze ograniczenie niż --allowedTools, które tylko zatwierdza narzędzia z góry: claude -p startuje w trybie Manual (od v2.1.285 w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią) i choć wszystko, co wymagałoby zgody, zostaje odrzucone (nikt nie odpowie na pytanie), tryb Manual nadal bez pytania wykonuje odczyty plików i wbudowane polecenia powłoki tylko do odczytu. W CI dodaj --max-budget-usd, żeby ograniczyć koszt, i nigdy nie uruchamiaj tego joba na niezaufanym kodzie z pull requesta, gdy w środowisku jest sekret. Bezpieczny wzorzec CI opisuje strona CI/CD z Claude Code.

Skąd wiesz, że praca z bazą jest poprawna?

Sprawdzasz dowody, które zostawia każdy krok, a nie podsumowanie agenta i nie każdą linię SQL.

Wynik	Bramka, która go dowodzi	Kto zatwierdza
Projekt schematu	Plan wymienia zapytania, które obsługuje, i ograniczenie za każdym niezmiennikiem	Ty, zanim zatwierdzisz tryb planowania
Plik migracji	Squawk przechodzi; up, down, up na świeżej bazie z pustym diffem schematu; CI to powtarza	Właściciel schematu, przez `CODEOWNERS` na katalogu migracji
Zapytanie albo indeks	`EXPLAIN (ANALYZE)` przed i po na tych samych danych; po wdrożeniu średni czas tego zapytania w `pg_stat_statements`	Autor, z planami w pull requeście
Funkcja ORM	Test, który sprawdza dokładne wiersze, łącznie z przypadkami granicznymi	CI
Skrypt seedujący	Dwa uruchomienia, identyczne liczby wierszy	CI

Recenzent czyta opis pull requesta, plany i diff schematu, a uwagę poświęca liniom, których bramki nie ocenią: zachowaniu przy usuwaniu, nieodwracalnym krokom i danym, które opuszczają bazę. Samą recenzję opisuje strona jak recenzować pull request agenta.

Co psuje się przy pracy z bazą w Claude Code i jak z tego wyjść

Migracja blokuje dużą tabelę. Instrukcja była poprawna, ale wzięła blokadę ACCESS EXCLUSIVE, na przykład ALTER TABLE … ADD COLUMN … NOT NULL DEFAULT z niestałą wartością domyślną albo indeks budowany bez CONCURRENTLY. Wyjście: anuluj migrację, jeśli nadal czeka (SELECT pg_cancel_backend(pid) dla zablokowanej instrukcji), a potem uruchom ponownie prompt migracji z liczbą wierszy w nagłówku pliku i zastosuj wzorce bez przestojów.

CREATE INDEX CONCURRENTLY cannot run inside a transaction block. Twoje narzędzie migracji owija każdy plik transakcją. Przenieś indeks do osobnej migracji i użyj udokumentowanego w tym narzędziu sposobu uruchomienia pliku poza transakcją.

Migracja SQLite albo Cloudflare D1 pada na ALTER TABLE. SQLite obsługuje ADD COLUMN, RENAME COLUMN (od 3.25.0) i DROP COLUMN (od 3.35.0, z ograniczeniami), ale nie zmianę typu kolumny ani dodanie ograniczenia do istniejącej kolumny, i nie ma ADD COLUMN IF NOT EXISTS. Poproś Claude Code o sekwencję przebudowy tabeli (nowa tabela, kopia, usunięcie, zmiana nazwy). W zwykłym SQLite wykonaj ją w jednej transakcji, z PRAGMA foreign_keys = OFF ustawionym przed jej rozpoczęciem. W D1 nie dodawaj BEGIN/COMMIT: D1 sam wykonuje plik migracji w transakcji (Wrangler 4.135.0 usuwa pojedynczą parę BEGIN TRANSACTION;/COMMIT; i odrzuca plik z więcej niż jedną), więc zamiast tego użyj w pliku PRAGMA defer_foreign_keys = on. W obu przypadkach przetestuj przebudowę na kopii prawdziwych danych, bo to przy kopiowaniu giną wiersze.

Claude Code uruchomił migrację na złej bazie. Sesja odziedziczyła DATABASE_URL, które wskazywało staging. Wyjście: zastosuj tam migrację down albo odtwórz bazę z kopii zapasowej zrobionej przed zmianą. Zapobieganie: uruchamiaj sesje z powłoki z bazą roboczą i przed pracą z bazą sprawdź w sesji echo $DATABASE_URL.

Skrypt seedujący łamie klucz obcy albo duplikuje wiersze przy drugim uruchomieniu. Wstawiał w złej kolejności albo używał zwykłych insertów. Uruchom ponownie prompt seedujący, który wymaga kolejności kluczy obcych i upsertów po kluczach naturalnych, i zostaw test „uruchom dwa razy, porównaj liczby”.

Migracja down istnieje, ale nie przywraca danych. Usunięcie kolumny w ścieżce up i ponowne dodanie jej w ścieżce down daje pustą kolumnę. Traktuj każdy destrukcyjny krok up jako nieodwracalny: zrób kopię zapasową albo zostaw starą kolumnę do fazy contract i napisz to na początku down.sql.

Claude Code po migracji wciąż używa starej nazwy kolumny. Pracuje na swoim wcześniejszym rozumowaniu, a nie na aktualnym schemacie. Poproś go o ponowne przeczytanie pliku schematu albo uruchom /clear i zacznij kolejne zadanie w świeżym kontekście.

Dokąd dalej przy pracy z bazą danych

Migracje baz danych i kodu Expand-contract, backfill w partiach i aktualizacje frameworków z Claude Code.

Serwery MCP dla baz danych Daj agentowi dostęp tylko do odczytu do żywego schematu i statystyk zapytań.

Wzorce optymalizacji SQL Przepisy niezależne od narzędzia: plany EXPLAIN, zapytania N+1 i indeksy.

Budowa API Zbuduj endpointy na świeżo wdrożonym schemacie.

Ten sam proces w innych narzędziach: praca z bazą danych w Codex i projektowanie bazy w Cursorze. Widok wspólny dla wszystkich narzędzi znajdziesz na stronie projektowanie baz danych i zapytań.