Przejdź do głównej zawartości

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.

  • 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

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 agentCo robi na dużej, obciążonej tabeliNapisz zamiast niej
ALTER COLUMN … TYPE (większość zmian typu)Przepisuje tabelę pod ACCESS EXCLUSIVEExpand-contract: nowa kolumna, backfill, przełączenie, usunięcie
ALTER COLUMN … SET NOT NULLSkanuje całą tabelę pod ACCESS EXCLUSIVECHECK (col IS NOT NULL) NOT VALID, potem VALIDATE CONSTRAINT, potem SET NOT NULL
CREATE INDEXBlokuje zapisy na cały czas budowyCREATE INDEX CONCURRENTLY we własnej migracji, poza transakcją
ADD FOREIGN KEY / ADD CHECKSkanuje, blokując zapisyDodaj jako NOT VALID, potem osobno VALIDATE CONSTRAINT
Jeden UPDATE na wszystkich wierszachDługa transakcja, blokady wierszy, rozrost tabeliPartie po około 1000 wierszy według klucza głównego, z możliwością wznowienia
Dowolne DDL bez limitu czasuMoż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

Dział zatytułowany „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.

    -- 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.

    // 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.

    -- 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.

    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.

    -- 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;
    -- 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.

    -- 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.

Daj agentowi żywy schemat przez serwer MCP tylko do odczytu

Dział zatytułowany „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 (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.

Okno terminala
# 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”.

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 opisuje zakresy i aktualizacje.

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

Dział zatytułowany „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 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.

Okno terminala
# 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.

# .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.

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.

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

Dział zatytułowany „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.

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.

Okno terminala
# 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.

Kopiuj dane między tabelami wznawialnym, walidowanym zadaniem wsadowym

Dział zatytułowany „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.

// 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ś:

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 kopiuje tabelę i synchronizuje ją triggerami. gh-ost działa bez triggerów: odtwarza zmiany z binary logu, co zdejmuje narzut triggerów z mocno zapisywanej tabeli źródłowej.

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.

FazaWycofanieRyzyko dla danych
ExpandALTER TABLE products DROP COLUMN IF EXISTS price_cents;Brak; kolumna nie miała jeszcze danych
Wdrożenie podwójnego zapisuWdróż ponownie poprzednią wersję aplikacjiBrak; price nadal jest zapisywane
BackfillZatrzymaj zadanie; nie ma czego cofaćBrak; uruchom ponownie później
Przełączenie odczytówWdróż ponownie wersję z podwójnym zapisemBrak; 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 003cPrzed 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_centsWysokie: 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.

Czy ten artykuł Ci pomógł?

Jedno kliknięcie, bez logowania.

wcale bardzo