Migrace DB v legacy bez ORM: struktura a praxe

Systém migrace databází pro legacy projekty bez ORM

V legacy systémech bez ORM vyžadují migrace DDL/DML skriptů striktní kontrolu. Navrhovaný přístup organizuje repozitář a tabulky stavu pro postupnou aplikaci změn v testovacích a produkčních prostředích. To zajišťuje sledovatelnost, podporu dat a předvídatelnost nasazení na relačních DBMS s ACID.

Přístup minimalizuje boilerplate ve skriptech, automatizuje kontrolu a logování. Skripty se dělí na typy: inicializace, baseline, versioned a repeatable. Každý typ se aplikuje podle pravidel, vylučuje duplicity a zajišťuje monotónnost verzí.

Struktura Git repozitáře

Skripty se seskupují podle typů a aplikují se v pevném pořadí:

• Inicializace prostředí — jednou pro vytvoření uživatelů, rolí, databází a schémat. Závisí na prostředí (test/prod), provádí se přes psql.
• Baseline — jednou na prázdném schématu pro počáteční verzi z produkce a kontrolních tabulek.
• Versioned — postupně podle rostoucích verzí (celé číslo), pouze jednou, v transakci s logem času a uživatele.
• Repeatable — při změně SHA256 nebo nepřítomnosti záznamu, po versioned, pro view/procedures/triggers bez měnitelných dat.

Typy objektů:

• Inicializace: uživatelé, role, databáze, schémata.
• Baseline: tabulky, data, pohledy, procedury, triggery.
• Versioned: změny schémat, migrace dat.
• Repeatable: pohledy, procedury, triggery.

Tato struktura je inspirována Flyway, ale adaptována pro manuální procesy bez externích nástrojů.

Tabulky stavu ve schématu

V každém schématu se vytvářejí služební tabulky pro sledování:

• dbmigration_versions (version_id, is_baseline, created_at, created_by, created_from) — historie baseline a versioned skriptů.
• dbmigration_repeatable (sha256sum, relative_path, created_at, created_by, created_from) — historie repeatable, umožňuje znovu aplikaci při změnách.

Tabulky zajišťují kontrolu před aplikací: skript se provede, pokud záznam neexistuje nebo se změnil checksum. Logy zahrnují uživatele a timestamp pro audit.

Nasazení ve vývoji

V CI/CD (GitLab pipeline) se klonuje větev se změnami, pak pro každé schéma:

$ git clone <url obsahující změny ve schématech databáze>
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <databáze> --user <uživatelské jméno> schema1 ./db/schema1
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <databáze> --user <uživatelské jméno> schema2 ./db/schema2

To automaticky aplikuje čekající skripty, zachovávaje data.

Proces v produkci

Podporuje se hot deployment bez downtime. Předtím se testuje v UAT s smoke-testy.

Kroky:

• Rozbalit archiv: tar xzvf system-x.y.z.tar.gz.
• Pro schéma: cd system-x.y.z/schema1.
• Vygenerovat migrační skript: USER_PASSWORD=topsecret123 dbmigration.py verify --host <host> --port <port> --dbname <databáze> --user <uživatelské jméno> --build-update-script ./schema1_migrate.sql schema1 ./db/schema1.
• Revidovat schema1_migrate.sql na breaking changes.
• Aplikovat: PGPASSWORD=topsecret123 psql -h <host> -p <port> -U <uživatel> -d <databáze> -v schema_name=<schema1> -f "schema1_migrate.sql".

Opakovat pro schémata. Režim verify umožňuje náhled bez změn.

Klíčové postupy

• Fix forward: místo rollback nová migrace opravuje chyby, zachovávaje data.
• Non-breaking changes: přidávat tabulky/pole, mazat po vydání, když se nepoužívají. Umožňuje paralelní práci verzí na jedné databázi.
• Sledování na úrovni schémat: verze per schema, ne per DB.
• Předběžná kontrola: generování skriptů pro revizi.
• Zachování dat: incremental updates bez drop/recreate.

Co je důležité

• Automatizované sledování vylučuje manuální boilerplate a chyby ve skriptech.
• Monotónní verze s transakcemi zajišťují konzistenci stavů.
• Podpora hotfix pro různé verze (prod/UAT/dev) přes versioned skripty.
• Audit přes tabulky: kdo/kdy/co aplikoval.
• RDBMS-agnostic pro ACID-kompatibilní DBMS.

— Editorial Team