Slovník pojmů

Databázová migrace

Databázová migrace převádí schéma aplikace bezpečně mezi verzemi. Není to jen SQL soubor: musí být čitelná, otestovaná, provozně promyšlená a slučitelná s právě nasazovaným kódem.

Stručná definice

Historie změn schématu místo ručních zásahů do databáze.

Databázová migrace je malý krok, který popisuje přechod známého schématu na další verzi: například vytvoření tabulky, přidání sloupce, indexu, constraintu nebo promyšlené převedení dat. Migrační nástroj eviduje, které verze již konkrétní databáze provedla, a spouští chybějící kroky ve správném pořadí.

Migrace není totéž co automatická synchronizace entit nebo náhodně spuštěné SQL z administrace. Změna schématu se verzovatelně kontroluje v kódu, prochází review a testem. Vývojář tak může posoudit dopad na starší i novější verzi aplikace, velikost tabulek, indexy, databázové zámky a plán návratu, pokud se nasazení nepodaří.

K čemu se používá

Vývoj schématu bez ručního rozcházení prostředí

Migrace dávají databázové změně stejnou dohledatelnost jako změně aplikačního kódu.

nové tabulky, sloupce, enum hodnoty, indexy a databázové constrainty
rozšíření objednávkového procesu o stav, externí identifikátor nebo trasovací číslo
přesuny a doplnění dat při změně modelu, pokud jsou bezpečné a přiměřeně malé
sjednocení lokálního vývoje, testovací databáze, stagingu a produkce na stejné verzi schématu
auditovatelný podklad pro review, nasazení a řešení incidentu způsobeného změnou dat

Praktický příklad

Přidání trasovacího čísla bez odstávky objednávek

E-shop potřebuje do objednávek přidat tracking_number od dopravce. Bezpečný první krok vytvoří nový nullable sloupec a případný podpůrný index, ale ještě nevynutí hodnotu pro staré objednávky. Nový kód umí hodnotu zapisovat a při čtení pracuje s tím, že starší objednávka ji ještě nemá.

Historická data se doplňují po dávkách samostatným procesem s monitoringem, nikoliv dlouhým jednorázovým UPDATE uprostřed kritického nasazení. Až když je aplikace i data připravená, následuje další samostatná změna: například NOT NULL nebo unikátní constraint. Tento postup rozděluje riziko a dovoluje návrat k předchozí verzi aplikace, aniž by starý kód narazil na neznámé schéma.

Postup změny

Expand, migrate, contract: schéma a aplikace se mění postupně

U provozované aplikace není databáze jednorázová instalace. Bezpečná změna dává po určitou dobu prostor starému i novému kódu.

Návrh dopadu Určí se dotčené tabulky, objem dat, constrainty, přístupové vzory i to, zda změněné schéma uvidí současně dvě verze aplikace.
Expand První migrace přidá kompatibilní strukturu, například nullable sloupec nebo novou tabulku. Staré čtení i zápis mohou dál fungovat.
Nasazení kódu Aplikace začne novou strukturu používat, ale zůstane tolerantní k dřívějším datům. Podle potřeby zapisuje do starého i nového místa.
Převod dat Backfill proběhne po kontrolovatelných dávkách mimo kritickou requestovou cestu. Sleduje se průběh, chyby i případné zatížení databáze.
Contract Až po ověření lze odstranit starý sloupec, zpřísnit constraint nebo zjednodušit kód. Destruktivní krok patří do samostatné vědomé změny.

Hlavní části a pojmy

Změna schématu má technickou i provozní stránku.

Nástroj vytvoří historii provedených kroků, ale sám nemůže znát provozní riziko konkrétní tabulky a aplikace.

Verze a historie

Každá migrace má jedinečný identifikátor a nástroj eviduje, zda proběhla. Nejde jen o pořadí souborů: historie pomáhá dohledat, z jakého stavu databáze změna vychází.

Schema versus data

Přidání sloupce je změna schématu. Přepočet milionů řádků je datová operace s jiným zatížením, délkou běhu a možností opakování; často patří do samostatného procesu.

Up a down

Některé nástroje umí popsat krok vpřed i zpět. Down ale není automatická záruka rollbacku: ztracená data, spuštěný backfill nebo externě použitá hodnota nemusí jít bezpečně vrátit.

Automaticky vytvořený diff

Diff mezi modelem a databází může urychlit první návrh. Vygenerované SQL se ale vždy kontroluje, protože nástroj nezná význam dat, provozní čas ani záměr změny.

Transakce, zámky a čas

Podpora transakčního DDL i chování indexů se liší podle databáze a typu operace. Na velké tabulce může i správné SQL způsobit čekání; rozhoduje plán, test a vhodné okno nasazení.

Vztah k ostatním nástrojům

Migrační nástroj není jedinou částí bezpečné databázové změny.

Doctrine Migrations, frameworkové migrace i vlastní proces sledují podobný cíl. Kvalita závisí na návrhu kroku a disciplíně kolem něj.

Doctrine Migrations: Nástroj pro verzované PHP migrace, který ukládá provedené verze a umí zobrazit či spustit chybějící kroky. Nezaručuje, že konkrétní SQL je bezpečné pro produkční data.
Doctrine DBAL: Umožňuje pracovat s databázovou platformou a SQL. Schéma migrace a aplikační DBAL dotazy musejí být kompatibilní během celého rollout okna.
ORM: Entity a mapování reagují na nové sloupce či tabulky, ale nejsou zdrojem pravdy pro každé databázové pravidlo. Constrainty a indexy je potřeba ověřit samostatně.
CI/CD a observabilita: Kontroly před nasazením, staging, metriky, logy a schopnost zastavit postup dávají migraci provozní kontext, který žádný jeden příkaz nenahradí.

Výhody a omezení

Dohledatelnost změny nezruší její riziko.

Přínosy

stejné a dohledatelné schéma napříč vývojem, testem a produkcí
reviewovatelný záznam změny tabulek, indexů a databázových pravidel
možnost plánovat kompatibilní rollout místo velkého jednorázového přepnutí
reprodukovatelné založení nového prostředí i diagnostika starší verze aplikace

Rizika a časté chyby

destruktivní změna bez zálohy, ověření a realistického plánu návratu
dlouhý backfill nebo budování indexu v kritické requestové cestě
spoléhání na automaticky vygenerovanou migraci bez review výsledného SQL
nasazení kódu, který předbíhá schéma nebo neumí přečíst dosavadní data

Kdy dává smysl

Jakmile databázi sdílí více prostředí nebo lidí, ruční postup přestává stačit.

Migrace jsou praktické pro API, e-shop, interní systém i malou aplikaci, která má staging nebo bude dlouhodobě rozvíjená. Přinášejí řád do situace, kdy tým přidá constraint, upraví integraci a potřebuje, aby vývojová databáze i produkce měly přesně vysvětlitelný stav.

U jednorázového prototypu může být plnohodnotný migrační proces nadbytečný, ale ruční změny rychle ztrácejí historii. U větších či citlivých dat není správná otázka jen „umí nástroj vytvořit sloupec?“, ale „co se stane při souběhu, rollbacku, výpadku nebo pomalém převodu dat?“.

Na co myslet

Každý krok musí být čitelný pro databázi i provoz.

Před produkčním spuštěním se ověřuje obsah migrace, podoba dat a pořadí kroku vůči nasazovanému kódu.

spouštět a testovat migrace na kopii nebo realisticky velkém stagingovém schématu
kontrolovat výsledné SQL, dry-run, délku běhu, indexy, constrainty a databázové zámky
rozšiřovat schéma kompatibilně a mazat starou strukturu až v navazujícím kroku
velké datové převody dělat dávkově s monitoringem, možností pokračovat a idempotentním výsledkem
mít pro destruktivní změnu ověřenou zálohu, postup obnovy a jasného vlastníka nasazení

Časté otázky

Migrace v dlouhodobě provozované aplikaci

Stačí migraci nechat automaticky vygenerovat?

Ne. Generátor může být dobrý začátek, ale nezná význam dat, zatížení tabulky ani kompatibilitu starého kódu. Výsledné SQL i postup nasazení potřebují review.

Lze každou migraci bezpečně vrátit pomocí down?

Ne vždy. Smazaná data, spuštěný převod nebo změna, kterou už použil jiný systém, nemusí mít bezpečný technický opak. Důležitější je předem navržený rollback aplikace a obnova dat.

Patří velký backfill do stejné migrace jako nový sloupec?

Obvykle ne. Dlouhý převod je lépe spouštět dávkově mimo kritickou cestu, monitorovat ho a zachovat možnost opakovat jen nedokončenou část.

Může migrace zablokovat produkční provoz?

Ano, podle databáze, typu změny, velikosti tabulky a souběhu. Proto se změny zkouší na reprezentativním prostředí, plánují a rozdělují do menších kompatibilních kroků.

Jak pracuji s databázemi v praxi

Změny datového modelu navrhuji s ohledem na provoz aplikace.

V e-commerce a integračních projektech řeším model dat, transakce, importy i bezpečný postup změny schématu bez zbytečného rizika pro provoz.

Jak pracuji s databázemi Nezávazně probrat projekt