# Wzorce migracji baz danych

URL: https://developertoolkit.ai/pl/cookbook/database-recipes/migration-patterns/
Description: Migracje Postgresa bez przestojów w Claude Code, Codeksie i Cursorze, udowodnione linterem Squawk, zapytaniem zgodności i planem wycofania każdej fazy.

Migracje baz danych bez przestojów z agentami AI dzielą każdą ryzykowną zmianę schematu na fazy expand, backfill i contract, wdrażane osobno. Claude Code, Codex albo Cursor pisze SQL na podstawie żywego schematu odczytanego przez serwer MCP tylko do odczytu, a linter migracji, zapytanie zgodności i plan wycofania każdej fazy dowodzą bezpieczeństwa bez czytania kodu linijka po linijce.

Ten przepis jest dla programisty, który odpowiada za zmianę schematu Postgresa, i dla tech leada, który ją zatwierdza. Poprosiłeś agenta o zmianę `products.price` z dolarów na centy w liczbach całkowitych. Oddał jedno schludne `ALTER TABLE products ALTER COLUMN price TYPE integer USING round(price * 100)`, testy przeszły, a o 14:00 Postgres założył blokadę `ACCESS EXCLUSIVE`, żeby przepisać tabelę z 40 milionami wierszy. Każde zapytanie z koszyka stanęło za nią w kolejce. Migracja była poprawna. Nie była bezpieczna, a nic w twoim pipeline’ie nie sprawdzało tej różnicy.

## Co wyniesiesz z tego przepisu

- Tabelę blokad, która mówi, które instrukcje Postgresa blokują ruch i co napisać zamiast nich
- **Prompt expand-contract**, który tworzy osobne, niezależnie wdrażalne migracje, kod podwójnego zapisu i wycofanie dla każdej fazy
- **Serwer MCP Postgresa tylko do odczytu** podłączony do Claude Code, Codeksa i Cursora, dzięki któremu agent planuje na prawdziwym schemacie
- **Bramkę weryfikacji** do CI: linter migracji Squawk, próbne zastosowanie na jednorazowej bazie i zapytanie zgodności, które musi zwrócić zero, zanim faza contract trafi na produkcję
- Runbook naprawczy na kolejki blokad, przerwane backfille, nieprawidłowe indeksy i nieaktualne wiersze zapisane przez stare wersje aplikacji

## Dlaczego poprawna migracja i tak kładzie produkcję?

Postgres wykonuje większość DDL pod blokadą `ACCESS EXCLUSIVE`, która blokuje odczyty i zapisy w tabeli. Instrukcja trzymająca tę blokadę przez milisekundy jest nieszkodliwa. Instrukcja trzymająca ją podczas przepisywania albo skanowania dużej tabeli to awaria. Co gorsza, instrukcja DDL, która tylko **czeka** na blokadę, blokuje każde zapytanie, które przyjdzie po niej. Długi raport potrafi więc zamienić milisekundowy `ALTER` w kolejkę, która zatrzymuje całą tabelę.

Agenci piszą krótką, oczywistą formę każdej instrukcji, bo na pustej bazie testowej jest ona poprawna. Poniższa tabela to wiedza recenzencka, której agentowi brakuje. Umieść ją w prompcie i w bramce lintera.

| Instrukcja, którą pisze agent | Co robi na dużej, obciążonej tabeli | Napisz zamiast niej |
| --- | --- | --- |
| `ALTER COLUMN … TYPE` (większość zmian typu) | Przepisuje tabelę pod `ACCESS EXCLUSIVE` | Expand-contract: nowa kolumna, backfill, przełączenie, usunięcie |
| `ALTER COLUMN … SET NOT NULL` | Skanuje całą tabelę pod `ACCESS EXCLUSIVE` | `CHECK (col IS NOT NULL) NOT VALID`, potem `VALIDATE CONSTRAINT`, potem `SET NOT NULL` |
| `CREATE INDEX` | Blokuje zapisy na cały czas budowy | `CREATE INDEX CONCURRENTLY` we własnej migracji, poza transakcją |
| `ADD FOREIGN KEY` / `ADD CHECK` | Skanuje, blokując zapisy | Dodaj jako `NOT VALID`, potem osobno `VALIDATE CONSTRAINT` |
| Jeden `UPDATE` na wszystkich wierszach | Długa transakcja, blokady wierszy, rozrost tabeli | Partie po około 1000 wierszy według klucza głównego, z możliwością wznowienia |
| Dowolne DDL bez limitu czasu | Może stanąć za długim zapytaniem i zablokować wszystko za sobą | Najpierw `SET lock_timeout = '5s'`, a przy błędzie ponów |

`VALIDATE CONSTRAINT` bierze tylko blokadę `SHARE UPDATE EXCLUSIVE`, więc odczyty i zapisy trwają podczas skanu. Sekwencja `NOT NULL` z trzeciej kolumny działa w PostgreSQL 12 i nowszych: gdy zwalidowane ograniczenie `CHECK` dowodzi, że kolumna nie ma wartości null, `SET NOT NULL` pomija skan. Całą sekwencję poniżej uruchomiliśmy 26 września 2026 r. na PostgreSQL 16 z `SET client_min_messages = debug1`, a Postgres zgłosił na poziomie `DEBUG1` „existing constraints on column "products.price_cents" are sufficient to prove that it does not contain nulls”.

## Podziel ryzykowną zmianę na expand, backfill i contract

Expand-contract (zwany też parallel change) nigdy nie zmienia kolumny w miejscu. Dodajesz nowy kształt, zapisujesz do obu, kopiujesz stare dane, przełączasz odczyty, a stary kształt usuwasz w późniejszym wydaniu. Każda faza to osobne wdrożenie, więc między dowolnymi dwiema możesz się zatrzymać, poobserwować i wycofać.

Kolejność jest ważniejsza niż SQL. Backfill rusza **dopiero wtedy**, gdy każda instancja aplikacji zapisuje podwójnie. Inaczej stara instancja może zaktualizować `price` już po tym, jak backfill minął dany wiersz, a `price_cents` po cichu się zdezaktualizuje.

1. **Expand.** Dodaj kolumnę dopuszczającą null. To zmiana wyłącznie metadanych, więc blokada trwa milisekundy.

   ```sql
   -- 001_expand_add_price_cents.sql
   SET lock_timeout = '5s';
   SET statement_timeout = '5s';
   ALTER TABLE products ADD COLUMN IF NOT EXISTS price_cents integer;
   ```

2. **Wdróż podwójny zapis.** Wypuść kod aplikacji, który zapisuje obie kolumny i czyta nową z fallbackiem na starą. Poczekaj, aż nie działa już żadna instancja starej wersji.

   ```javascript
   // node-postgres. The ::integer casts are required: without them Postgres
   // rejects the statement with "inconsistent types deduced for parameter $1".
   async function setProductPrice(productId, priceCents) {
     await db.query(
       `UPDATE products
          SET price_cents = $1::integer, price = $1::integer / 100.0
        WHERE id = $2`,
       [priceCents, productId],
     );
   }

   async function getProductPriceCents(productId) {
     // Round in SQL, exactly as the backfill does. In JavaScript 1.005 * 100 is
     // 100.49999..., so Math.round would return 100 where Postgres returns 101.
     const { rows } = await db.query(
       'SELECT coalesce(price_cents, round(price * 100)::integer) AS cents FROM products WHERE id = $1',
       [productId],
     );
     return rows[0].cents;
   }
   ```

3. **Backfill partiami.** Uruchamiaj tę instrukcję poza transakcją, raz za razem, aż zaktualizuje zero wierszy. Każde uruchomienie to krótka transakcja, a przerwany przebieg wznawia się tam, gdzie stanął. Filtr `price IS NOT NULL` jest ważny: bez niego wiersze bez ceny są „aktualizowane” do NULL i wybierane ponownie przy każdym przebiegu, więc pętla nigdy się nie kończy.

   ```sql
   -- 002_backfill_price_cents.sql
   UPDATE products
      SET price_cents = round(price * 100)
    WHERE id IN (
      SELECT id FROM products
       WHERE price_cents IS NULL
         AND price IS NOT NULL
       ORDER BY id
       LIMIT 1000
    );
   ```

   Wiersze, w których `price` ma wartość NULL, zostają z NULL w `price_cents`, a faza contract poniżej nie ustawi tej kolumny na `NOT NULL`, dopóki one istnieją. Policz je teraz (`SELECT count(*) FROM products WHERE price IS NULL`) i zdecyduj przed wydaniem z fazą contract: wypełnij je jawną wartością domyślną albo zostaw `price_cents` jako kolumnę dopuszczającą null, pomiń ograniczenie CHECK i `SET NOT NULL` z plików 003a–003c, a `price` i tak usuń.

4. **Udowodnij zgodność.** To zapytanie jest wyrocznią całej migracji. Musi zwrócić `0` przed przełączeniem odczytów i ponownie na początku wydania z fazą contract, gdy każda instancja nadal zapisuje obie kolumny.

   ```sql
   SELECT count(*) AS mismatched
     FROM products
    WHERE price_cents IS DISTINCT FROM round(price * 100);
   ```

5. **Przełącz odczyty na `price_cents` i nadal zapisuj podwójnie.** Wdróż kod, który czyta tylko `price_cents`, ale wciąż zapisuje obie kolumny. Po wdrożeniu ponownie uruchom zapytanie zgodności. Ponieważ `price` jest nadal zapisywane, wycofanie aplikacji do wersji z podwójnym zapisem pozostaje bezpieczne przez całą tę fazę.

6. **Contract.** W późniejszym wydaniu potwierdź, że zgodność wynosi `0`, a potem uruchom trzy pliki, każdy we **własnej transakcji**. Większość narzędzi migracji (Flyway, Rails, Prisma, node-pg-migrate, golang-migrate na Postgresie) opakowuje każdy plik w jedną transakcję. Jeśli `ADD CONSTRAINT` i `VALIDATE CONSTRAINT` dzielą transakcję, blokada `ACCESS EXCLUSIVE` z pierwszej instrukcji trwa przez cały skan walidacji, a to jest dokładnie ta awaria, przed którą chroni ta strona. `lock_timeout` tu nie pomoże: ogranicza czas czekania na blokadę, a nie to, jak długo trzyma ją skan.

   ```sql
   -- 003a_contract_add_check.sql
   SET lock_timeout = '5s';
   SET statement_timeout = '5s';
   ALTER TABLE products
     ADD CONSTRAINT price_cents_not_null CHECK (price_cents IS NOT NULL) NOT VALID;
   ```

   ```sql
   -- 003b_contract_validate_check.sql (SHARE UPDATE EXCLUSIVE: reads and writes continue)
   SET lock_timeout = '5s';
   SET statement_timeout = '30min'; -- sized to the full scan, not to the lock wait
   ALTER TABLE products VALIDATE CONSTRAINT price_cents_not_null;
   ```

   Potem wdróż kod, który przestaje zapisywać `price`, i zaraz po nim uruchom ostatni plik. Od tego wdrożenia `price` się dezaktualizuje, więc to punkt, po którym nie ma już taniego powrotu.

   ```sql
   -- squawk-ignore-file adding-not-nullable-field, ban-drop-column
   -- 003c_contract_drop_price.sql
   SET lock_timeout = '5s';
   SET statement_timeout = '5s';
   ALTER TABLE products ALTER COLUMN price_cents SET NOT NULL; -- skips the scan: the check proves it
   ALTER TABLE products DROP CONSTRAINT IF EXISTS price_cents_not_null;
   ALTER TABLE products DROP COLUMN IF EXISTS price;
   ```

   Pierwsza linia celowo wyłącza dwie reguły Squawka, tylko dla tego pliku. `adding-not-nullable-field` nie widzi ograniczenia `CHECK` zwalidowanego w 003b, więc zgłasza skan tabeli, którego Postgres nie wykona. `ban-drop-column` ostrzega przed usunięciem kolumny, a to jest zamierzony krok fazy contract. Wszystkie pozostałe reguły zostaw włączone.

Nie musisz pisać tej sekwencji samodzielnie. Pisze ją agent. Twoim zadaniem jest przekazać mu powyższe ograniczenia i sprawdzić wynik bramką opisaną niżej.

**Prompt do skopiowania: wygeneruj migrację expand-contract**

```text
Read the current definition of the products table (use the postgres MCP server if it is
connected; otherwise read db/schema.sql). The table has about 40 million rows and constant
checkout traffic on PostgreSQL 16.

Replace products.price (numeric dollars) with products.price_cents (integer cents) with zero
downtime, using expand-contract. Write separate files in db/migrations/:
1. expand: SET lock_timeout = '5s', then add price_cents as a nullable column.
2. backfill: batches of 1000 rows by id where price IS NOT NULL, safe to re-run until
   it updates 0 rows, run outside a transaction. Tell me how many rows have a NULL
   price; I decide on a default or a nullable price_cents before the contract phase.
3. contract (for a later release), as three files that each run in a separate
   transaction: (a) CHECK (price_cents IS NOT NULL) NOT VALID; (b) VALIDATE CONSTRAINT;
   (c) SET NOT NULL, drop the check, drop price. Tell me whether our migration tool
   wraps several files in one transaction.

Also write:
- dual-write setProductPrice and fallback-read getProductPriceCents for node-postgres,
  with explicit ::integer casts on reused parameters;
- read-switch code that still writes both columns, and the code change that stops
  writing price, to ship in the contract release right before file (c);
- the parity query that must return 0 before the contract phase;
- a rollback statement for each migration file.

For every statement, name the lock it takes and say whether it can run at peak traffic.
Do not use ALTER COLUMN ... TYPE, a bare CREATE INDEX, or an unbatched UPDATE.
Do not run anything against the database.
```

## Daj agentowi żywy schemat przez serwer MCP tylko do odczytu

Powyższy prompt jest tak dobry, jak schemat, który czyta agent. Jeśli wkleisz stary wynik `\d products`, agent zaplanuje migrację tabeli, która już nie istnieje. Serwer MCP dla Postgresa pozwala agentowi samodzielnie odczytać typy kolumn, szacunkową liczbę wierszy i istniejące indeksy, a potem dobrać do nich wielkość partii.

[Postgres MCP Pro](https://github.com/crystaldba/postgres-mcp) (PyPI `postgres-mcp`, od Crystal DBA) ma jawny tryb dostępu: `--access-mode=restricted` ogranicza go do transakcji tylko do odczytu z limitem czasu wykonania. Uruchamiaj go przez `uvx`. Dwie przestrogi z naszego sprawdzenia z 26 września 2026 r.: najnowsze wydanie na PyPI to 0.3.0 z 16 maja 2025 r., więc przypnij wersję i obserwuj repozytorium, a pakiet npm o tej samej nazwie `postgres-mcp` jest niezwiązany, więc nie uruchamiaj go przez `npx`. Stary pakiet `@modelcontextprotocol/server-postgres` jest w npm oznaczony jako przestarzały i zarchiwizowany; nie używaj go.

Konfiguracja serwera jest taka sama we wszystkich trzech narzędziach. Różni się tylko sposób rejestracji.

**Claude Code**

```bash
# Terminal, in the repository root. Put the server name BEFORE -e:
# -e takes several values, so a name after it is read as another variable.
claude mcp add postgres -e DATABASE_URI=postgresql://agent_ro@localhost:5432/app_staging \
  -- uvx postgres-mcp --access-mode=restricted
```

Dodaj `--scope project`, żeby zapisać serwer w `.mcp.json` i dać go całemu zespołowi. Sprawdziliśmy obie kolejności w Claude Code 2.1.283: powyższa działa, a `--env KEY=value postgres -- …` kończy się błędem „Invalid environment variable format: postgres”.

**Codex**

```bash
# Terminal. Registers the server in Codex's config.toml.
codex mcp add postgres --env DATABASE_URI=postgresql://agent_ro@localhost:5432/app_staging \
  -- uvx postgres-mcp --access-mode=restricted
```

`codex mcp list` pokazuje wynik. Sprawdzone z `codex mcp add --help` w Codex CLI 0.157.1.

**Cursor**

Dodaj serwer do `.cursor/mcp.json` w projekcie. To ten sam kształt `mcpServers`, który Claude Code zapisuje w `.mcp.json`:

```json
{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://agent_ro@localhost:5432/app_staging"
      }
    }
  }
}
```

**Tylko do odczytu w dwóch miejscach i nigdy na głównej bazie produkcyjnej**

Tryb restricted wymusza odczyt w samym serwerze, a README Postgres MCP Pro zaznacza, że niebezpieczne języki procedur składowanych potrafią to obejść. Wymuś to także w bazie: łącz się rolą, która ma wyłącznie `SELECT` (powyższe `agent_ro`), na kopii stagingowej albo replice do odczytu. Agent czyta schemat, a samą migrację uruchamia wyłącznie twoje wersjonowane narzędzie do migracji. Zobacz, [jak bezpiecznie ograniczyć serwery MCP dla baz danych](/pl/ecosystem/mcp/database-mcp/), oraz [listę kontrolną bezpieczeństwa MCP](/pl/ecosystem/mcp/mcp-security/).

Jeśli potrzebujesz wiedzy recenzenckiej o Postgresie, a nie żywego połączenia, lżejszy jest skill. Skill `supabase-postgres-best-practices` od Supabase obejmuje wydajność Postgresa i row-level security; zainstalujesz go poleceniem `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices` (CLI `skills` miało 26 września 2026 r. wersję 1.7.0 w npm). Skill nie czyta twojej bazy, więc używaj go obok serwera MCP, a nie zamiast niego. [Instalowanie skilli i zarządzanie nimi](/pl/ecosystem/skills/installing-managing/) opisuje zakresy i aktualizacje.

## Zabezpiecz każdą migrację linterem, prawdziwym zastosowaniem i zapytaniem zgodności

Prośba, by agent zrecenzował własną migrację, łapie część zagrożeń, ale SQL ocenia wtedy ten sam model, który go napisał. Postaw przed scaleniem deterministyczną bramkę, a człowiekowi zostaw ocenę dowodów, które ta bramka wytwarza.

[Squawk](https://github.com/sbdchd/squawk) to linter migracji PostgreSQL (npm `squawk-cli`, 2.66.0 na 26 września 2026 r.). Uruchomiliśmy go na pliku z czterema niebezpiecznymi instrukcjami z tabeli blokad. Zgłosił wszystkie cztery, w tym „Setting a column `NOT NULL` blocks reads while the table is scanned”, dodał ostrzeżenia `require-lock-timeout` i zakończył się kodem 1, a to oblewa zadanie CI. Squawk zwraca 1 zarówno przy błędach, jak i przy ostrzeżeniach, więc zielone zadanie oznacza zero zgłoszeń, a nie tylko zero błędów.

```bash
# CI or terminal: lint only the migrations this branch adds.
npx squawk-cli@2.66.0 $(git diff --name-only --diff-filter=A origin/main -- 'db/migrations/*.sql')

# Apply the chain to a throwaway Postgres. The backfill does 1,000 rows per run,
# so repeat it until no row is left, then check parity. The counter stops a loop
# that never converges (1,000 runs covers a 1-million-row seed).
psql "$TEST_DATABASE_URL" -v ON_ERROR_STOP=1 -f db/migrations/001_expand_add_price_cents.sql
runs=0
until [ "$(psql "$TEST_DATABASE_URL" -At -c \
  'SELECT count(*) FROM products WHERE price_cents IS NULL AND price IS NOT NULL')" = 0 ]; do
  runs=$((runs + 1))
  [ "$runs" -le 1000 ] || { echo "backfill did not converge" >&2; exit 1; }
  psql "$TEST_DATABASE_URL" -v ON_ERROR_STOP=1 -f db/migrations/002_backfill_price_cents.sql
done
psql "$TEST_DATABASE_URL" -At -c \
  "SELECT count(*) FROM products WHERE price_cents IS DISTINCT FROM round(price * 100)"
```

Trzy ustawienia dopasowują Squawka do twojego narzędzia migracji. Jeśli narzędzie opakowuje każdy plik w transakcję, dodaj `--assume-in-transaction`, żeby Squawk analizował rzeczywiste wykonanie. W tym trybie Squawk 2.66.0 zgłasza `VALIDATE CONSTRAINT` w tym samym pliku co dodanie `NOT VALID` („Using `NOT VALID` and `VALIDATE CONSTRAINT` in the same transaction will block all reads while the constraint is validated”), czyli dokładnie pułapkę, której unikają trzy pliki fazy contract; sprawdziliśmy to 26 września 2026 r. Reguły, które cię nie dotyczą, trafiają do `.squawk.toml` albo `--exclude`, każda z uzasadnieniem. Z poniższą konfiguracją wszystkie pięć plików z tej strony przechodzi przez Squawk 2.66.0 z kodem wyjścia 0; sprawdziliśmy to 26 września 2026 r.

```toml
# .squawk.toml, in the repository root
# Our migration tool wraps each file in its own transaction.
assume_in_transaction = true
# price_cents holds cents: int4 allows about 21 million dollars per product.
excluded_rules = ["prefer-bigint-over-int"]
```

Squawk potrafi też komentować pull request poleceniem `squawk upload-to-github` albo przez [squawk-action](https://github.com/sbdchd/squawk-action).

Kto zatwierdza i na jakiej podstawie:

- **CI** blokuje scalenie przy każdym zgłoszeniu Squawka (także ostrzeżeniu), każdym nieudanym zastosowaniu migracji i niezerowym wyniku zapytania zgodności na zasilonej danymi bazie testowej.
- **Właściciel migracji** przegląda przygotowaną przez agenta listę blokad dla każdej instrukcji i wynik Squawka, a nie każdą linijkę SQL.
- **Wydanie z fazą contract** potrzebuje w pull requeście jeszcze jednego artefaktu: wyniku zapytania zgodności z produkcji (uruchomionego rolą tylko do odczytu), który pokazuje `0`. To element [pakietu dowodów dla pull requestów agenta](/pl/workflows/ship/evidence-bundle/).

**Prompt do skopiowania: przeprowadź migrację przez bramkę blokad**

```text
Run `npx squawk-cli@2.66.0 --assume-in-transaction` on every migration file this branch
adds under db/migrations/ and fix each finding. The products table has about 40 million rows and constant writes on
PostgreSQL 16. Specifically:
1. Put SET lock_timeout = '5s' before any statement that takes ACCESS EXCLUSIVE.
2. Replace ALTER COLUMN ... TYPE with an expand-contract sequence.
3. Replace SET NOT NULL with CHECK ... NOT VALID, VALIDATE CONSTRAINT, SET NOT NULL.
4. Use CREATE INDEX CONCURRENTLY in its own file, and tell me whether our migration tool
   wraps files in a transaction (it must not, for that file).
5. Add foreign keys and checks as NOT VALID, and validate them in a separate migration
   file, so the validation runs in its own transaction.
6. Batch any UPDATE or DELETE that touches the whole table.
7. Put SET statement_timeout before slow statements, sized to the operation.
8. Do not rewrite 003c's SET NOT NULL; it is covered by the CHECK validated in 003b,
   and the file's squawk-ignore-file line records that.
Squawk exits 1 on warnings as well as errors. Re-run it until it exits 0. If you keep a
finding on purpose, add it to .squawk.toml with a one-line reason. Finish with a table: file, statement, lock taken, safe at peak (yes/no).
```

## Uruchom pętlę migracji w Claude Code, Codeksie albo Cursorze

Prompty i bramka są takie same we wszystkich narzędziach. Różni się to, jak uruchamiasz pętlę bez nadzoru i gdzie przeglądasz wynik.

**Claude Code**

Wygeneruj, zlintuj i zastosuj migrację w jednym przebiegu bezobsługowym. `--allowedTools` z góry zatwierdza dokładnie te narzędzia. Sesja `claude -p` startuje w trybie Manual, a u zewnętrznych dostawców lub z wyłączoną telemetrią (od v2.1.285) w trybie auto, w którym decyduje klasyfikator, a nie lista dozwolonych narzędzi, więc każde inne wywołanie narzędzia, które wymagałoby pytania, odrzuca u każdego dostawcy dopiero `--permission-mode dontAsk`.

```bash
# Terminal or CI. TEST_DATABASE_URL points at a local throwaway database.
claude -p "Write an expand-contract migration in db/migrations/ that replaces \
products.price with products.price_cents, following docs/migrations.md. Then run \
exactly 'npx squawk-cli@2.66.0 --assume-in-transaction <new files>', apply them \
with 'npm run db:migrate' against the test database, run 'npm test -- migrations', \
and report the lock each statement takes." \
  --permission-mode dontAsk \
  --allowedTools "Read" "Edit" "Write" "Bash(npx squawk-cli@2.66.0 *)" \
  "Bash(npm run db:migrate)" "Bash(npm test *)" \
  --output-format json > migration-run.json
```

Każda reguła `Bash(...)` dopasowuje prefiks polecenia, więc `Bash(npx squawk-cli *)` odrzuciłaby przypięte `npx squawk-cli@2.66.0`; trzymaj regułę i prompt przy tej samej pisowni. `--allowedTools` pomija pytania o wymienione narzędzia. Żeby całkowicie usunąć z sesji wszystkie pozostałe, użyj zamiast niego `--tools`. Zachowaj `migration-run.json` jako zapis CI tego, co zostało uruchomione. Flagi sprawdzone z `claude --help` 2.1.283.

**Codex**

Uruchom zmianę w nowym, zarządzanym worktree Gita, żeby nigdy nie dotknęła twojej roboczej kopii.

```bash
# Terminal. network_access lets the sandboxed commands reach the local test database.
codex exec --worktree --sandbox workspace-write \
  -c sandbox_workspace_write.network_access=true \
  "Write an expand-contract migration in db/migrations/ replacing products.price with \
products.price_cents: expand, batched backfill run outside a transaction, and contract \
split into add-check, validate and drop files that each run in their own transaction. Run npx squawk-cli@2.66.0 on the new files, apply them to TEST_DATABASE_URL, run the \
migration tests, and list the lock each statement takes."
```

W trybie `workspace-write` dostęp do sieci jest wyłączony, dopóki nie ustawisz `sandbox_workspace_write.network_access`, więc bez tego krok zastosowania migracji nie dosięgnie Postgresa. Wyeksportuj `TEST_DATABASE_URL` przed uruchomieniem. Jeśli krok zastosowania migracji zgłasza pustą zmienną, twoje `shell_environment_policy` odfiltrowuje ją z poleceń w sandboksie: dodaj `-c shell_environment_policy.inherit=all` (w formie z `codex --help`) albo wpisz URL w prompt. Dodaj `--json`, żeby dostać dziennik zdarzeń w JSONL. Flagi sprawdzone z `codex exec --help` w Codex CLI 0.157.1.

**Cursor**

Zacznij w Plan Mode od promptu expand-contract, żeby agent zaproponował podział na pliki, zanim cokolwiek napisze. Sprawdź w planie dwie rzeczy: krok contract jest podzielony na **osobne pliki** (dodanie CHECK, walidacja, usunięcie), oddzielone od expand, a backfill ma `LIMIT` i klauzulę `WHERE`, która pozwala go wznowić.

Potem pozwól agentowi napisać pliki i przejrzyj diff wielu plików, zanim go zaakceptujesz. Uruchom polecenia Squawka i zastosowania migracji z sekcji o bramce w zintegrowanym terminalu albo zostaw je CI. Zrób commit przed akceptacją dużej edycji, żeby `git restore` zawsze było twoją drogą powrotu.

## Kopiuj dane między tabelami wznawialnym, walidowanym zadaniem wsadowym

Gdy przekształcasz dane, a nie kolumnę, na przykład przenosisz `legacy_users` do `users`, agent powinien przygotować zadanie wsadowe z czterema cechami: paginacją po kluczu, idempotentnymi zapisami, odrzuconymi wierszami zapisywanymi zamiast przerywania przebiegu oraz zapytaniem uzgadniającym na końcu.

```javascript
// Batched copy from legacy_users to users. db is a node-postgres client.
async function migrateUsers({ batchSize = 1000, startAfterId = 0 } = {}) {
  let cursor = startAfterId;
  const rejected = [];

  for (;;) {
    const { rows } = await db.query(
      'SELECT id, email_address FROM legacy_users WHERE id > $1 ORDER BY id LIMIT $2',
      [cursor, batchSize],
    );
    if (rows.length === 0) break;

    for (const row of rows) {
      const email = row.email_address?.trim().toLowerCase();
      if (!email?.includes('@')) {
        rejected.push({ id: row.id, reason: 'invalid email' });
        continue;
      }
      await db.query(
        'INSERT INTO users (email, legacy_id) VALUES ($1, $2) ON CONFLICT (legacy_id) DO NOTHING',
        [email, row.id],
      );
    }
    cursor = rows[rows.length - 1].id; // log this: it is your resume point
  }
  return { lastId: cursor, rejected };
}
```

`WHERE id > $1 ORDER BY id` pozostaje szybkie na dowolnej głębokości, a `OFFSET` zwalnia z każdą stroną. `ON CONFLICT (legacy_id) DO NOTHING` sprawia, że ponowne uruchomienie jest bezpieczne, pod warunkiem że `users.legacy_id` ma ograniczenie unikalności. Zadanie jest skończone, gdy to zapytanie zwraca wyłącznie wiersze, które świadomie odrzuciłeś:

```sql
SELECT l.id FROM legacy_users l
LEFT JOIN users u ON u.legacy_id = l.id
WHERE u.legacy_id IS NULL;
```

W MySQL poproś agenta, żeby sterował sprawdzonym narzędziem do zmian schematu online, zamiast ręcznie pisać triggery. [`pt-online-schema-change`](https://docs.percona.com/percona-toolkit/pt-online-schema-change.html) kopiuje tabelę i synchronizuje ją triggerami. [`gh-ost`](https://github.com/github/gh-ost) działa bez triggerów: odtwarza zmiany z binary logu, co zdejmuje narzut triggerów z mocno zapisywanej tabeli źródłowej.

## Jak wycofać każdą fazę migracji?

Expand-contract daje tanie wycofanie w każdej fazie oprócz ostatniej. Wklej tę tabelę do pull requesta, żeby dyżurny nie musiał jej wymyślać o 2:00 w nocy.

| Faza | Wycofanie | Ryzyko dla danych |
| --- | --- | --- |
| Expand | `ALTER TABLE products DROP COLUMN IF EXISTS price_cents;` | Brak; kolumna nie miała jeszcze danych |
| Wdrożenie podwójnego zapisu | Wdróż ponownie poprzednią wersję aplikacji | Brak; `price` nadal jest zapisywane |
| Backfill | Zatrzymaj zadanie; nie ma czego cofać | Brak; uruchom ponownie później |
| Przełączenie odczytów | Wdróż ponownie wersję z podwójnym zapisem | Brak; w tej fazie `price` jest nadal zapisywane |
| Contract: dodanie i walidacja CHECK (003a, 003b) | `ALTER TABLE products DROP CONSTRAINT IF EXISTS price_cents_not_null;` | Brak; obie kolumny są nadal zapisywane |
| Contract: koniec zapisu `price`, potem 003c | Przed 003c: wypełnij ponownie `price` z `price_cents`, potem wdróż wersję z podwójnym zapisem. Po 003c: odtwórz z kopii zapasowej albo dodaj `price` z powrotem i wypełnij z `price_cents` | Wysokie: od tego wdrożenia `price` się dezaktualizuje, a `DROP COLUMN` to jedyny krok, którego nie cofniesz czysto |

Ten ostatni wiersz wyjaśnia, dlaczego faza contract czeka jedno wydanie, wymaga wyniku zgodności z produkcji i uruchamia 003c zaraz po wdrożeniu, które przestaje zapisywać `price`. Zanim ją uruchomisz, zrób kopię zapasową albo przynajmniej `pg_dump --table=products` tabeli, którą zmieniasz.

## Gdy migracje baz danych się psują

**Zapytania przekraczają limit czasu w chwili startu migracji**

Instrukcja DDL czeka na blokadę za długim zapytaniem, a każde nowe zapytanie stoi w kolejce za DDL. Najpierw anuluj migrację; kolejka od razu się rozładuje. Znajdź blokujące zapytanie przez `SELECT pid, now() - xact_start AS age, state, query FROM pg_stat_activity WHERE state <> 'idle' ORDER BY age DESC;`, dodaj do migracji `SET lock_timeout = '5s'` i ponów ją w spokojniejszym oknie. Gdyby Squawk działał w CI, brak limitu zostałby wychwycony przez regułę `require-lock-timeout`.

**Backfill spowalnia bazę albo pada w połowie**

Zatrzymaj zadanie. Zmniejsz partię do 500 wierszy i dodaj przerwę między partiami, żeby autovacuum nadążał z martwymi wierszami. Backfill filtruje po `price_cents IS NULL` (albo stronicuje po `id > cursor`), więc ponowne uruchomienie pomija wiersze już przetworzone. Poproś agenta: „Rewrite this backfill to process 500 rows per batch with a 50 ms pause, log the last id every 10 batches, and accept a start id so it can resume.”

**Zapytanie zgodności zwraca wiersze po zakończonym backfillu**

Instancja aplikacji ze starą wersją zapisała `price` bez `price_cents` albo backfill ruszył, zanim podwójny zapis dotarł do każdej instancji. Potwierdź, że wszystkie instancje działają na wersji z podwójnym zapisem, a potem uruchom partię naprawczą z `WHERE price_cents IS DISTINCT FROM round(price * 100)` zamiast `IS NULL`. Powtarzaj zapytanie zgodności, aż zwróci `0`. Nie wdrażaj fazy contract, dopóki tak się nie stanie.

**CREATE INDEX CONCURRENTLY się nie udało i zostawiło nieprawidłowy indeks**

Nieudana budowa współbieżna zostawia indeks `INVALID`, który nadal spowalnia każdy zapis. Znajdź go przez `SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;`, usuń przez `DROP INDEX CONCURRENTLY` i zbuduj ponownie. Ponowienie bez usunięcia zostawia drugi nieprawidłowy indeks. Jeśli budowa padła z błędem „cannot run inside a transaction block”, twoje narzędzie migracji opakowało plik w transakcję; przenieś instrukcję do pliku, który z tego rezygnuje.

**Nie wiesz, która faza jest aktywna**

To bezpieczny tryb awarii expand-contract: dopóki stara kolumna istnieje, a aplikacja nadal ją zapisuje, nic nie jest zepsute. To przestaje być prawdą, gdy wydanie contract wdroży kod, który nie zapisuje już `price`; jeśli to wdrożenie działa, a 003c jeszcze nie, dokończ 003c zamiast wycofywać aplikację. Sprawdź kolumny (`\d products`), sprawdź, jaką wersję aplikacji ma każda instancja, uruchom zapytanie zgodności i kontynuuj od pierwszej niezakończonej fazy. Nigdy nie przeskakuj do fazy contract, żeby „dokończyć sprawę”.

## Dokąd dalej

- Przed tą stroną: [praca z bazą danych przez serwer MCP](/pl/workflows/build/database-development/) opisuje projektowanie schematu i zapytania na żywym połączeniu.
- [Porównanie serwerów MCP dla baz danych](/pl/ecosystem/mcp/database-mcp/): który serwer pasuje do twojej bazy i jak ograniczyć jego dostęp.
- [Wzorce ORM](/pl/cookbook/database-recipes/orm-patterns/): te same zasady bezpieczeństwa, gdy migrację generuje Prisma albo TypeORM.
- [Wzorce optymalizacji SQL](/pl/cookbook/database-recipes/sql-patterns/): wybór indeksów na podstawie `EXPLAIN ANALYZE`, za którym powinny iść twoje współbieżne budowy indeksów.
- Szczegóły dla narzędzi: [migracje w Claude Code](/pl/claude-code/build/migrations/) i [praca z bazą danych w Codeksie](/pl/codex/build/database-work/).
- Po tej stronie: [progressive delivery](/pl/workflows/ship/progressive-delivery/), czyli stopniowe wdrażanie podwójnego zapisu i przełączenia odczytów, oraz [pakiet dowodów](/pl/workflows/ship/evidence-bundle/), czyli to, czego musi dowieść pull request z migracją.
