Wzorce migracji baz danych

O 14:00 wdrożyłeś niewinnie wyglądające ALTER TABLE products ALTER COLUMN price TYPE numeric. Postgres założył blokadę ACCESS EXCLUSIVE, żeby przepisać tabelę z 40 milionami wierszy, każde zapytanie z koszyka ustawiło się w kolejce za nim, a sklep zaczął zwracać błędy 500 przez dziewięć minut, podczas gdy twój PM patrzył, jak wykres błędów pnie się w górę. Migracja była „poprawna” — po prostu nie była bezpieczna.

Rozwiązaniem nie jest pisanie SQL-a ręcznie z większą uwagą. Rozwiązaniem jest pozwolić agentowi AI wygenerować migrację, a potem sprawić, by sam zrecenzował swoją pracę pod kątem dokładnie tych zagrożeń, które wywołują incydenty: długich blokad, niepartiowanych backfillów i indeksów budowanych bez CONCURRENTLY. Ten przepis pokazuje cały przepływ pracy w Cursorze, Claude Code i Codeksie.

Co z tego wyniesiesz

• Wielokrotnego użytku prompt expand-contract, który zamienia ryzykowny, jednorazowy ALTER w trzy bezpieczne, ponumerowane migracje plus kod aplikacji z podwójnym zapisem
• Prompt do recenzji bezpieczeństwa migracji, który zgłasza blokady ACCESS EXCLUSIVE, brakujące CONCURRENTLY i niepartiowane UPDATE, zanim cokolwiek uruchomisz
• Podłączony serwer MCP Postgresa tylko do odczytu, dzięki któremu agent czyta twój żywy schemat, zamiast zgadywać typy kolumn
• Przepis na rollback i runbook „Gdy to się zepsuje” na wypadek rywalizacji o blokady, niedokończonych backfillów i częściowego stanu migracji

Przepływ pracy expand-contract

Najużyteczniejszym pojedynczym wzorcem dla zmian bez przestojów jest expand-contract (zwany też parallel change): nigdy nie zmieniaj kolumny w miejscu. Dodaj nowy kształt, zapisuj podwójnie do obu, wypełnij dane partiami, przełącz odczyty, a dopiero w późniejszym wdrożeniu usuń stary kształt. Każdy krok da się wdrożyć i cofnąć niezależnie.

Incydent ze zmianą typu kolumny z początku staje się trzema migracjami zamiast jedną:

-- 001_expand_add_price_cents.sql  (deploy 1: dodaj kolumnę nullable, bez przepisywania, bez blokady)
ALTER TABLE products ADD COLUMN price_cents integer;

-- 002_backfill_price_cents.sql    (deploy 1+: uruchom POZA transakcją, partiami)
-- Powtarzaj, aż zaktualizowanych zostanie 0 wierszy. Każda instrukcja to krótka, osobna transakcja.
UPDATE products
SET price_cents = round(price * 100)
WHERE price_cents IS NULL
  AND id IN (
    SELECT id FROM products WHERE price_cents IS NULL ORDER BY id LIMIT 1000
  );

-- 003_contract_drop_price.sql     (deploy 3, dni później: dopiero gdy podwójny zapis działa)
ALTER TABLE products ALTER COLUMN price_cents SET NOT NULL;
ALTER TABLE products DROP COLUMN price;

Pomiędzy deployem 1 a deployem 3 aplikacja zapisuje podwójnie i czyta nową kolumnę z rozwiązaniem zapasowym, dzięki czemu stara i nowa wersja kodu bezpiecznie współistnieją:

// Podwójny zapis, dopóki istnieją obie kolumny (faza przejściowa)
async function setProductPrice(productId, priceCents) {
  await db.query(
    `UPDATE products
     SET price_cents = $1, price = $1 / 100.0
     WHERE id = $2`,
    [priceCents, productId]
  );
}

// Czytaj nową kolumnę, wróć do starej do czasu zakończenia backfillu
async function getProductPriceCents(productId) {
  const { rows } = await db.query(
    'SELECT price, price_cents FROM products WHERE id = $1',
    [productId]
  );
  return rows[0].price_cents ?? Math.round(rows[0].price * 100);
}

Nie musisz pisać tego z pamięci. Podaj agentowi swój prawdziwy schemat i pozwól mu wyprodukować całą sekwencję.

Wskazówka

Prompt do skopiowania — wygeneruj migrację expand-contract:

Here is my Postgres products table:

products(id uuid pk, name text, price numeric(10,2) not null, created_at timestamptz)

Write a zero-downtime expand-contract migration that replaces price (numeric dollars) with price_cents (integer cents). Produce three numbered SQL files: (1) expand — add the nullable column with no table rewrite; (2) backfill — update in batches of 1000 by id, designed to run repeatedly outside a transaction until no rows remain; (3) contract — set NOT NULL then drop price, to ship in a later deploy. Also give me the dual-write setProductPrice and fallback-read getProductPriceCents functions for node-postgres, and a one-line rollback for each migration. Do not use CREATE INDEX without CONCURRENTLY.

Pozwól agentowi zobaczyć prawdziwy schemat (MCP Postgresa)

Prompt powyżej działa, ale schemat trzeba było wkleić ręcznie — a jeśli pomylisz typ kolumny, agent wygeneruje migrację względem tabeli, która nie istnieje. Serwer MCP Postgresa likwiduje tę lukę: daje agentowi połączenie, więc może obejrzeć żywe definicje tabel, liczby wierszy i istniejące indeksy, zanim napisze choćby linijkę. Użyj utrzymywanego serwera — Postgres MCP Pro (crystaldba/postgres-mcp) to aktywnie wspierany wybór, a jego flaga --access-mode=restricted wymusza dostęp tylko do odczytu na poziomie serwera. (Unikaj starego pakietu @modelcontextprotocol/server-postgres: jest przestarzały i zarchiwizowany oraz niesie znaną podatność na SQL injection, która pozwala spiętrzonej instrukcji wymknąć się z transakcji tylko do odczytu).

Bez MCP: kopiujesz wynik \d products do promptu i masz nadzieję, że jest aktualny. Z MCP: agent sam uruchamia odpowiednik SELECT … FROM information_schema.columns, widzi, że price jest typu numeric(10,2), a tabela ma 40 mln wierszy, i odpowiednio dobiera rozmiar partii oraz strategię blokad.

Postgres MCP Pro to narzędzie napisane w Pythonie — zainstaluj je przez pipx install postgres-mcp (lub uv pip install postgres-mcp). Konfiguracja jest potem identyczna we wszystkich trzech narzędziach, bo każde mówi w MCP. Dodaj serwer do swojej konfiguracji MCP, przekazując connection string przez DATABASE_URI i wymuszając tylko odczyt za pomocą --access-mode=restricted:

{
  "mcpServers": {
    "postgres": {
      "command": "postgres-mcp",
      "args": ["--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://readonly@localhost:5432/mydb"
      }
    }
  }
}

W przypadku Claude Code ten sam serwer dodasz z poziomu CLI:

claude mcp add --transport stdio \
  --env DATABASE_URI=postgresql://readonly@localhost:5432/mydb \
  postgres -- postgres-mcp --access-mode=restricted

Uwaga

Broń się warstwowo: uruchom serwer z --access-mode=restricted oraz wskaż mu naprawdę rolę bazy danych tylko do odczytu (sam GRANT SELECT), najlepiej na replice staging, a nie na produkcyjnym primary z poświadczeniami do zapisu. Nie opieraj się na jednej warstwie — wymuś tylko odczyt także na poziomie roli, żeby błąd po stronie serwera nie był jedyną rzeczą stojącą między agentem a twoimi danymi. Agent powinien planować względem prawdziwego schematu, nigdy nie modyfikować go bezpośrednio; właściwa migracja zawsze przechodzi przez twoje zrecenzowane, wersjonowane narzędzie migracyjne.

Jeśli wszystko, czego potrzebujesz, to „pozwolić agentowi uruchamiać bezpieczne zapytania tylko do odczytu” bez trwałego połączenia, lżejszą alternatywą jest Agent Skill, taki jak supabase/postgres-best-practices, instalowany poleceniem npx skills add supabase/agent-skills. Skille to jednofunkcyjne wzmocnienie; serwer MCP sprawdza się lepiej, gdy chcesz, by agent wielokrotnie introspekował żywą bazę danych w trakcie całej sesji.

Sterowanie tym w każdym z narzędzi

Pliki migracji i kod podwójnego zapisu produkuje wszędzie ten sam prompt — różni się jednak to, jak prowadzisz tę pętlę, recenzujesz diff i wdrażasz.

Cursor

Otwórz katalog migracji i przełącz wybór modelu na Claude Opus 4.8 (lub Claude Fable 5 przy najbardziej złożonych, wieloplikowych refaktoryzacjach, gdy budżet ma mniejsze znaczenie niż poprawność). W trybie Agent wklej powyższy prompt expand-contract. Cursor proponuje trzy pliki SQL plus zmiany w podwójnym zapisie jako edycję wieloplikową; zrecenzuj je w widoku diff, zanim zaakceptujesz.

Wizualny diff jest tu sednem: przeczytaj klauzulę partiowania WHERE … LIMIT 1000 i potwierdź, że migracja contract jest w osobnym pliku niż expand, abyś mógł wdrożyć je w różnych wydaniach. Użyj checkpointu przed akceptacją, żeby móc cofnąć edycję, jeśli agent posunie się za daleko. Następnie uruchom migrację przez swoje zwykłe narzędzie (npm run db:migrate) w zintegrowanym terminalu i obserwuj oczekiwanie na blokady.

Claude Code

Wygeneruj i zweryfikuj w jednym przebiegu bezgłowym — idealne do kroku CI lub powtarzalnego skryptu. Claude Code zapisuje pliki, a potem uruchamia twój zestaw testów migracji przez narzędzie Bash:

claude -p "Generate an expand-contract migration replacing products.price (numeric) \
with price_cents (integer) in db/migrations/. Three numbered files: expand, batched \
backfill (runs outside a transaction), contract. Then run 'npm run db:migrate' against \
the local test database and 'npm test -- migrations' and report failures." \
  --allowedTools "Read" "Write" "Edit" "Bash(npm run db:migrate)" "Bash(npm test *)" \
  --output-format json

--allowedTools wstępnie autoryzuje dokładnie te wzorce do uruchomienia bez pytania o uprawnienia, więc w tym bezgłowym przebiegu -p agent może udowodnić, że migracja się stosuje, a zestaw testów pozostaje zielony bez nadzoru — wszystko spoza listy zatrzymałoby się na zatwierdzenie, które nigdy nie nadejdzie. (Aby twardo ograniczyć dostępny zestaw narzędzi, a nie tylko pominąć pytania, użyj zamiast tego --tools). Przekieruj --output-format json do logów CI, by mieć audytowalny zapis tego, co zostało uruchomione.

Codex

Uruchom zmianę w odizolowanym worktree, żeby nigdy nie naruszyła twojego roboczego checkoutu. W aplikacji Codex (lub CLI codex) zacznij wątek na worktree opartym na main, a potem wklej prompt expand-contract.

Do uruchomienia skryptowego użyj codex exec w trybie nieinteraktywnym:

codex exec --cd ../app-migrations \
  "Add an expand-contract migration replacing products.price with price_cents. \
Three numbered files, batched backfill outside a transaction, contract separate. \
Run the migration test suite and summarize."

Gdy diff wygląda dobrze, kliknij Create branch here na worktree, wypchnij go i otwórz pull request na GitHubie prosto z wątku. Izolacja worktree sprawia, że długi eksperyment z backfillem nigdy nie blokuje gałęzi funkcji, którą edytujesz lokalnie.

Niech agent zrecenzuje własną migrację

Wygenerowanie migracji to połowa roboty. Druga połowa to wyłapanie produkcyjnych zagrożeń, które ludzki recenzent prześlizguje o 14:00. Dwa tryby awarii z incydentu z początku — blokady całych tabel i niepartiowane zapisy — to dokładnie to, co LLM wykrywa świetnie, gdy poprosisz go, żeby się temu przyjrzał.

Wskazówka

Prompt do skopiowania — recenzja bezpieczeństwa produkcyjnego:

Review this migration for production safety on a Postgres table with 40M rows. Flag and rewrite anything that would cause downtime, specifically:

1. Any statement that takes an ACCESS EXCLUSIVE lock (ALTER COLUMN … TYPE, adding a NOT NULL column with a volatile default, table rewrites).
2. CREATE INDEX without CONCURRENTLY (and remind me it can’t run inside a transaction block).
3. UPDATE/DELETE over the whole table without batching.
4. Adding a FOREIGN KEY or CHECK constraint validated immediately instead of NOT VALID + a later VALIDATE CONSTRAINT.

For each issue, show the safe rewrite and explain the lock it avoids.

Wklej swoją migrację po prompcie. To pojedynczy najbardziej dźwigniowy sprawdzian w całym przepływie pracy.

Kilka poprawek, które ta recenzja niezawodnie wydobywa:

• Budowanie indeksów: CREATE INDEX CONCURRENTLY idx_products_sku ON products(sku); zamiast samego CREATE INDEX. Forma współbieżna unika blokady ACCESS EXCLUSIVE — kosztem tego, że nie może działać wewnątrz bloku transakcji, więc musi być osobnym krokiem migracji.
• Nowe ograniczenia: dodaj jako NOT VALID, a potem ALTER TABLE … VALIDATE CONSTRAINT w osobnej instrukcji. Walidacja zakłada wtedy tylko blokadę SHARE UPDATE EXCLUSIVE i nie blokuje zapisów.
• Backfille: partiowane w pętli (jak w plikach expand-contract powyżej), nigdy jeden gigantyczny UPDATE, który trzyma blokady wierszy i puchnie tabelę martwymi krotkami.

Jeśli sam opakowujesz zmiany schematu online, wybierz sprawdzone w boju narzędzie zamiast ręcznie sklejanych wyzwalaczy. Dla MySQL pt-online-schema-change prowadzi kopiowanie i podmianę za pomocą wyzwalaczy, dobierając poprawnie jawne listy kolumn tam, gdzie ręcznie pisane wyzwalacze INSERT … SELECT NEW.* zawodzą (w MySQL NEW to referencja do wiersza, a nie tabela, z której można SELECT-ować). gh-ost podchodzi do tego odwrotnie — jest bezwyzwalaczowy, śledząc binary log, żeby odtwarzać zapisy na tabeli-widmie, co przy intensywnym ruchu zapisów utrzymuje narzut wyzwalaczy z dala od źródła. Poproś agenta, żeby wywołał jedno z nich, zamiast wymyślać je od nowa.

Zwalidowana migracja danych, którą naprawdę uruchomisz

Gdy przekształcasz dane — a nie tylko schemat — połącz migrację z walidującym, partiowanym kopiowaniem. Oto krótka, samodzielna wersja skupiona na pętli, którą generuje agent; trzymaj ją małą i pozwól, by prompt wyprodukował transform/validate specyficzne dla tabeli:

// Partiowane, walidowane kopiowanie ze starej tabeli. db to klient w stylu node-postgres.
async function migrateUsers({ batchSize = 1000 } = {}) {
  let cursor = 0;
  let migrated = 0;
  const errors = [];

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

    let successful = 0; // let, nie const — to jest inkrementowane poniżej
    for (const row of batch) {
      const email = row.email_address?.toLowerCase();
      if (!email || !email.includes('@')) {
        errors.push({ id: row.id, reason: 'invalid email' });
        continue;
      }
      await db.query(
        'INSERT INTO users (email, legacy_id) VALUES ($1, $2) ON CONFLICT (email) DO NOTHING',
        [email, row.id]
      );
      successful++;
    }

    migrated += successful;
    cursor = batch[batch.length - 1].id;
    console.info(`migrated ${migrated} (batch ${batch.length}, ${errors.length} skipped)`);
  }

  return { migrated, errors, ok: errors.length === 0 };
}

Zwróć uwagę na celowo nudne detale, które czynią ją bezpieczną na produkcji: paginacja keyset po id (a nie OFFSET, który zwalnia liniowo), ON CONFLICT DO NOTHING dla idempotentnych ponownych przebiegów, bramka walidacji, która zapisuje błędne wiersze zamiast się wywalać, oraz let successful = 0, aby licznik na partię faktycznie mógł rosnąć. Poproś agenta, żeby opakował każdą partię w transakcję, jeśli potrzebujesz semantyki wszystko-albo-nic dla pojedynczej partii.

Gdy to się zepsuje

Uwaga

Backfill trzyma blokadę, a zapytania przekraczają limit czasu. Twoja partia jest zbyt duża albo pętla nie ma pauzy. Zatrzymaj runner, zmniejsz batchSize (spróbuj 500) i dodaj krótkie pg_sleep/setTimeout między partiami, żeby autovacuum mógł odzyskać martwe krotki. Potwierdź, co blokuje, za pomocą SELECT pid, state, wait_event, query FROM pg_stat_activity WHERE state <> 'idle';, a w razie potrzeby SELECT pg_cancel_backend(pid); na rozszalałej instrukcji. Poproś agenta: „Rewrite this backfill to process 500 rows per batch with a 50ms pause and log progress every 10 batches.”

Uwaga

Backfill padł w połowie. Właśnie dlatego każdy backfill musi być idempotentny i wznawialny. Ponieważ pętla filtruje WHERE price_cents IS NULL (albo stronicuje po id > cursor), po prostu uruchamiasz ją ponownie — już zmigrowane wiersze są pomijane. Jeśli użyłeś ON CONFLICT DO NOTHING, ponowne kopiowanie danych również jest bezpieczne. Nigdy nie pisz backfillu, który zakłada, że uruchomi się dokładnie raz.

Uwaga

CREATE INDEX CONCURRENTLY zawiódł i zostawił nieprawidłowy indeks. Nieudana budowa współbieżna pozostawia po sobie indeks INVALID, który nadal pochłania zapisy. Znajdź go za pomocą SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;, usuń go przez DROP INDEX i ponownie uruchom budowę współbieżną. Nie ponawiaj bez wcześniejszego usunięcia — spiętrzysz zduplikowane nieprawidłowe indeksy.

Uwaga

Utknąłeś w częściowym stanie migracji — expand się wdrożył, contract nie, i nie masz pewności, co jest na żywo. To bezpieczny tryb awarii expand-contract: stara kolumna nadal istnieje, a aplikacja wciąż czyta ją przez rozwiązanie zapasowe, więc nic nie jest zepsute. Zweryfikuj inwentarz kolumn (\d products), potwierdź, że podwójny zapis jest wdrożony wszędzie, pozwól backfillowi się dokończyć i dopiero wtedy wdróż contract. Cały sens trzech osobnych wdrożeń polega na tym, że możesz zatrzymać się między dowolnymi z nich.

Co dalej

• Wzorce SQL — optymalizacja zapytań, którą agent zastosuje na twoich wolnych ścieżkach
• Wzorce ORM — generowanie bezpiecznych migracji przez Drizzle, Prismę i Knexa
• Wzorce NoSQL — migracje i backfille baz dokumentowych