Przepisy bazodanowe

Przepisy bazodanowe to cztery strony gotowych promptów dla Claude Code, Codeksa i Cursora: migracje schematu, kod ORM, optymalizacja SQL i modele danych NoSQL. Każdy przepis zakłada dwie rzeczy: agent czyta prawdziwy schemat przez połączenie tylko do odczytu, a bezpieczeństwo każdej zmiany udowadnia prawdziwy silnik bazy danych, a nie człowiek czytający SQL.

Ta strona jest dla programistów, którzy oddają agentowi bazodanową część nowej funkcji. Znasz ten scenariusz: migracja przechodzi na pustej lokalnej bazie, a na produkcji blokuje tabelę z 40 milionami wierszy. Albo agent wymyśla kolumnę, bo zgadł schemat z pliku modelu.

Który przepis bazodanowy pasuje do twojego zadania?

Wybieraj według zadania, które masz przed sobą, a nie według kolejności na liście.

Twoje zadanie	Przepis	Bramka, która to udowadnia
Zmiana nazwy, podział lub uzupełnienie kolumny bez przestoju	Wzorce migracji baz danych	Lint Squawkiem, zapytanie o zgodność danych zwracające zero wierszy, wycofanie dla każdej fazy
Modele Prisma lub TypeORM, zapytania N+1, transakcje	Najlepsze praktyki ORM	Testy integracyjne na prawdziwym Postgresie; liczba zapytań na żądanie
Wolne zapytanie albo brakujący indeks	Wzorce optymalizacji SQL	Postgres `EXPLAIN (ANALYZE, BUFFERS)` / MySQL `EXPLAIN ANALYZE` przed zmianą i po niej, na realistycznych danych
Modele danych w MongoDB, DynamoDB, Neo4j lub bazie wektorowej	Wzorce i strategie NoSQL	Testy wzorców dostępu na prawdziwym silniku

Pełny przepływ pracy wokół tych przepisów (specyfikacja, przegląd schematu, wdrożenie) opisuje strona praca z bazą danych z agentami AI.

Podłącz agenta do schematu, zanim użyjesz przepisu

Przepis uruchomiony na zgadniętym schemacie daje SQL, który wygląda przekonująco, a jest błędny. Najpierw daj agentowi dostęp tylko do odczytu do bazy lokalnej lub stagingowej. DBHub (Bytebase, npm @bytebase/dbhub 1.3.1 na 2026-09-26) obsługuje jednym serwerem Postgresa, MySQL, SQL Server, MariaDB, Oracle i SQLite. Podłącz go przez rolę, która może tylko czytać. O trybie tylko do odczytu decyduje dopiero brak uprawnień do zapisu; default_transaction_read_only wyłapuje jedynie pomyłki, bo sesja może go wyłączyć. Linia z domyślnymi uprawnieniami sprawia, że agent widzi też tabele utworzone przez kolejne migracje:

-- Uruchom raz w psql na bazie lokalnej lub stagingowej, jako rola, która wykonuje migracje.
-- \password pyta o hasło, więc nie trafia ono do historii powłoki.
CREATE ROLE agent_ro LOGIN;
\password agent_ro
GRANT CONNECT ON DATABASE app TO agent_ro;
GRANT USAGE ON SCHEMA public TO agent_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO agent_ro;
ALTER ROLE agent_ro SET default_transaction_read_only = on;

DBHub 1.3.1 odczytuje ciąg połączenia ze zmiennej środowiskowej DSN, więc hasło nie trafia ani do historii powłoki, ani do commitowanego pliku. Wyeksportuj AGENT_RO_DSN w powłoce z menedżera sekretów albo z nieśledzonego pliku .env (wartość ma postać postgres://agent_ro:<hasło>@localhost:5432/app). Rejestracja w trzech narzędziach różni się tylko składnią:

claude mcp add dbhub -e DSN="$AGENT_RO_DSN" -- npx @bytebase/dbhub@1.3.1 --transport stdio

codex mcp add dbhub --env DSN="$AGENT_RO_DSN" -- npx @bytebase/dbhub@1.3.1 --transport stdio

Dodaj serwer do .cursor/mcp.json. Plik zawiera tylko odwołanie do zmiennej, więc można go bezpiecznie commitować:

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["@bytebase/dbhub@1.3.1", "--transport", "stdio"],
      "env": { "DSN": "${env:AGENT_RO_DSN}" }
    }
  }
}

Polecenia Claude Code i Codeksa zapisują rozwinięty DSN otwartym tekstem w ~/.claude.json (domyślnie w zakresie local) albo w ~/.codex/config.toml, poza repozytorium; traktuj te pliki jak sekrety. Dokumentacja MCP Cursora opisuje interpolację ${env:NAZWA} w mcp.json; zanim zacommitujesz plik, sprawdź, czy działa w twojej wersji Cursora (np. czy serwer się łączy).

DBHub ma też własne zabezpieczenia, w tym tryb tylko do odczytu i limit wierszy (zobacz jego README). Traktuj je jako drugą warstwę; o bezpieczeństwie decyduje brak uprawnień do zapisu w roli.

Serwery dla konkretnych silników (Supabase, Neon, Postgres MCP Pro, MongoDB) porównuje strona serwery MCP dla baz danych.

Before writing any SQL or ORM code, use the dbhub MCP server to inspect the
tables this feature touches: columns, types, nullability, indexes, foreign keys,
and approximate row counts. Print them as a table. Then list every assumption
you would otherwise have made from the model files that the live schema
contradicts. Do not write code in this step.

Jak zweryfikować zmiany w bazie bez czytania każdej linii?

Niech recenzentem będzie baza danych. Zmiana jest gotowa, gdy przechodzi bramkę z tabeli powyżej, a agent dołącza jej wynik — nie wtedy, gdy SQL wygląda poprawnie.

Migracje: sprawdź każdy nowy plik migracji Squawkiem, potem zastosuj, wycofaj i zastosuj ponownie na jednorazowej kopii o wolumenie zbliżonym do produkcji, a zapytanie o zgodność danych uruchamiaj, aż zwróci zero. Ustaw lock_timeout, żeby polecenie czekające na blokadę szybko kończyło się błędem, zamiast ustawiać za sobą w kolejce wszystkie zapisy.
Uzupełnianie danych: porównaj liczby wierszy i sumę kontrolną zmienianych kolumn przed operacją i po niej.
Zapytania: dołącz wynik EXPLAIN (ANALYZE, BUFFERS) w Postgresie lub EXPLAIN ANALYZE w MySQL przed zmianą i po niej, uruchomiony na realistycznych danych. EXPLAIN ANALYZE wykonuje polecenie, więc przy zapisach opakuj je w BEGIN … ROLLBACK na jednorazowej kopii.
Kod ORM: testy integracyjne na prawdziwym silniku, na przykład w Postgresie z Testcontainers; zobacz testy integracyjne i zarządzanie danymi testowymi.

Człowiek zatwierdza jedną rzecz: każdy krok destrukcyjny (DROP, faza contract we wzorcu expand-contract). To zatwierdzenie trafia do pakietu dowodów w pull requeście.

Write this schema change as expand-contract migrations: expand now, contract in
a separate later migration. Then, against a local Docker Postgres restored
from an anonymised production-sized snapshot (not the MCP connection, which
is read-only):
1. Run npx squawk-cli@2.66.0 on each new migration file; fix every error.
2. Prepend SET lock_timeout = '2s'; to each migration file, so it fails fast
   in production instead of queuing writes behind a lock.
3. Apply, roll back, and re-apply each migration; paste the output.
4. Using the Squawk output and the row counts from the dbhub inspection, list
   every statement that takes an ACCESS EXCLUSIVE lock on a table over 1M rows.
5. For any backfill, print row counts and an md5 of the affected columns
   before and after.
Stop and ask me before writing any DROP or the contract migration.

Co się psuje, gdy agent pisze kod bazodanowy?

Wymyślone kolumny lub złe typy. Agent przeczytał model ORM, a nie bazę. Naprawa: uruchom prompt, który każe agentowi najpierw odczytać schemat, i dopisz do CLAUDE.md lub AGENTS.md regułę „cytuj aktualny schemat”.
Migracja zielona lokalnie, a na produkcji blokuje tabelę. Lokalna tabela miała 50 wierszy. Naprawa: powtórz bramkę na kopii o rozmiarze produkcji z ustawionym lock_timeout i podziel zmianę według przepisu wzorce migracji.
Zmiana nazwy w ORM wygenerowana jako usunięcie i dodanie kolumny. Diff modelu ukrywa utratę danych. Naprawa: przeglądaj wygenerowany SQL, a nie plik modelu, i wymagaj sprawdzenia liczby wierszy przy każdej migracji.
Indeks, który przyspiesza jedno zapytanie i spowalnia zapisy. Naprawa: przepis optymalizacja SQL każe agentowi oszacować koszt zapisu każdego nowego indeksu i odrzucić duplikaty istniejących.
Agent zapisał coś do współdzielonej bazy. Naprawa: łącz go wyłącznie przez rolę tylko do odczytu opisaną wyżej, a ograniczenia po stronie agenta opisuje strona uprawnienia i sandboxing.

Dokąd dalej z przepisami bazodanowymi

Wzorce migracji baz danych

Najlepsze praktyki ORM

Wzorce optymalizacji SQL

Wzorce i strategie NoSQL

Przepisy backendowe Przepisy językowe i frameworkowe dla usługi wokół bazy danych.