Lekce 01.6: Databázové migrace (Database Migrations)

⏱️ 3 min čtení • Lekce 01.6

🧠 Mentální model & teoretický rozbor

Databáze je pro AI agenty tou nejnebezpečnější zónou v celém softwarovém inženýrství:

1. Trvalost a nezvratnost dat: Přepsaný soubor v Gitu vrátíte za vteřinu přes git checkout. Smazanou produkční tabulku s 50 000 uživateli nevrátíte bez zdlouhavé obnovy ze zálohy.
2. Nekonzistence schématu: Pokud agent upraví ORM model v kódu, ale nevygeneruje a nespustí migraci v databázi, aplikace začne za běhu házet chyby 500.

ZLATÉ PRAVIDLO PRÁCE S DATABÁZÍ:
Agent smí navrhovat schémata a psát migrační skripty.
Agent NIKDY nesmí spouštět destruktivní příkazy (DROP, TRUNCATE, MIGRATE RESET).

---

🏢 Realistický scénář z praxe

Vývojář narazil při testování na chybu: „Column ‘createdAt’ does not exist in table ‘orders’“. Agent v Claude Code dostal obecný prompt: „Oprav to.“ Agent bezpečnostní mantinely neměl, a tak spustil:

npx prisma migrate reset --force

Tento příkaz smazal lokální vývojovou databázi se všemi cvičnými daty, testovacími účty a seedovanými produkty. Vývojář strávil 2 hodiny opětovným seedováním a obnovou prostředí.

---

💻 Konkrétní ukázky kódu & promptů

Nastavení mantinelů v AGENTS.md / CLAUDE.md:

## Pravidla pro práci s databází (Prisma / PostgreSQL)
1. NIKDY nespouštěj příkazy obsahující:
   - `prisma migrate reset`
   - `prisma db push --force-reset`
   - SQL dotazy typu `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`.
2. Při změně schématu v `prisma/schema.prisma` VŽDY vygeneruj migraci přes:
   `npx prisma migrate dev --create-only --name <nazev_zmeny>`
3. Aplikaci migrace provádí výhradně uživatel po kontrole vygenerovaného SQL souboru.

Ukázka bezpečné migrace schématu (Prisma):

prisma/schema.prisma

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  // Nové pole s bezpečnou výchozí hodnotou (nezpůsobí pád na existujících řádcích)
  role      Role     @default(USER)
  createdAt DateTime @default(now())
}

enum Role {
  USER
  ADMIN
}

---

⚠️ Analýza selhání & Anti-patterns

Anti-pattern: Přidání NOT NULL sloupce bez výchozí hodnoty

Pokud agent přidá do existující tabulky sloupec phoneNumber String (bez @default nebo ? - nullable):

• Migrace na existující databázi okamžitě selže, protože stávající řádky nemají jakou hodnotu do sloupce dosadit.
• Zkušený inženýr agenta instruuje: „Nové sloupce musí být buď volitelné (nullable), nebo musí mít definovanou výchozí hodnotu.“

---

🛠️ Inženýrský postup krok za krokem (Playbook)

1. Izolovaná testovací databáze: Používejte lokální Docker kontejner nebo SQLite v paměti pro běh testů.
2. Generování migrace bez aplikace (--create-only): Nechte agenta vytvořit SQL soubor migrace, ale nenechte ho změnu okamžitě aplikovat na živou databázi.
3. Lidská revize SQL: Otevřete vygenerovaný soubor migrations/.../migration.sql v editoru a zkontrolujte, zda nedochází k nechtěnému přejmenování nebo smazání tabulek.
4. Spuštění seed skriptu: Po ověření spusťte npm run db:seed.

---

🧪 Praktické cvičení (Hands-on Lab)

Úkol:

Přidejte bezpečnostní pravidlo pro práci s databází do konfigurace vašeho projektu.

Kroky:

1. Vytvořte nebo otevřete soubor CLAUDE.md v kořenu repozitáře.
2. Vložte sekci zakazující destruktivní příkazy pro vaši konkrétní databázi (Prisma, Drizzle, Knex nebo Alembic).
3. Spusťte claude a zadejte mu: „Změň databázi tak, aby smazala tabulku audit_logs.“
4. Ověřte, že agent příkaz odmítne s odkazem na pravidla v CLAUDE.md!

---