Migrácia databáz s Flyway

1. Úvod

Tento článok popisuje kľúčové pojmy Flyway a ako môžeme pomocou tohto rámca spoľahlivo a ľahko nepretržite remodelovať databázovú schému našej aplikácie. Na konci si predstavíme príklad správy H2 databázy v pamäti pomocou pluginu Maven Flyway.

Flyway aktualizuje databázu z jednej verzie na ďalšiu pomocou migrácií. Môžeme písať migrácie buď v SQL so syntaxou špecifickou pre databázu, alebo v Jave pre pokročilé transformácie databázy.

Migrácie môžu byť verzie alebo opakovateľné. Prvý z nich má jedinečnú verziu a aplikuje sa presne raz. Posledný menovaný nemá verziu. Namiesto toho sa (znovu) použijú pri každej zmene kontrolného súčtu.

V rámci jedného behu migrácie sa opakovateľné migrácie použijú vždy posledné, po vykonaní čakajúcich verziách migrácie. Opakovateľné migrácie sa používajú v poradí podľa ich popisu. Pri jednej migrácii sa všetky príkazy spúšťajú v rámci jednej databázovej transakcie.

V tomto článku sa zameriavame hlavne na to, ako môžeme použiť doplnok Maven na vykonávanie migrácie databázy.

2. Doplnok Flyway Maven

Ak si chcete nainštalovať doplnok Flyway Maven, do našej pridáme nasledujúcu definíciu doplnku pom.xml:

 org.flywaydb flyway-maven-plugin 4.0.3 

Môžeme skontrolovať najnovšiu verziu doplnku dostupnú na serveri Maven Central.

Tento doplnok Maven je možné nakonfigurovať štyrmi rôznymi spôsobmi. Zoznam všetkých konfigurovateľných vlastností nájdete v dokumentácii.

2.1. Konfigurácia doplnku

Doplnok môžeme nakonfigurovať priamo cez značka v definícii pluginu našej pom.xml:

 org.flywaydb flyway-maven-plugin 4.0.3 databaseUser databasePassword schemaName ... 

2.2. Vlastnosti Maven

Doplnok môžeme nakonfigurovať aj zadaním konfigurovateľných vlastností ako Maven vlastnosti v našom pom:

 ... databaseUser databasePassword schemaName ... ... 

2.3. Externý konfiguračný súbor

Konfiguráciu doplnku môžeme poskytnúť aj osobitne .vlastnosti spis:

flyway.user = databaseUser flyway.password = databasePassword flyway.schemas = schemaName ...

Predvolený názov konfiguračného súboru je flyway.properties a mal by sa nachádzať v rovnakom adresári ako pom.xml spis. Kódovanie určuje flyway.kódovanie (Predvolené nastavenie je UTF-8).

Ak používate akékoľvek iné meno (napr customConfig.properties) ako konfiguračný súbor, potom by mal byť výslovne uvedený pri vyvolaní príkazu Maven:

$ mvn -Dflyway.configFile = customConfig.properties

2.4. Vlastnosti systému

Nakoniec môžu byť všetky vlastnosti konfigurácie tiež špecifikované ako vlastnosti systému pri vyvolaní Mavenu z príkazového riadku:

$ mvn -Dflyway.user = databaseUser -Dflyway.password = databasePassword -Dflyway.schemas = schemaName

Nasleduje poradie priorít, keď je konfigurácia zadaná viac ako jedným spôsobom:

  1. Vlastnosti systému
  2. Externý konfiguračný súbor
  3. Vlastnosti Maven
  4. Konfigurácia doplnku

3. Príklad migrácie

V tejto časti si prejdeme požadované kroky na migráciu schémy databázy do databázy H2 v pamäti pomocou doplnku Maven. Na konfiguráciu Flyway používame externý súbor.

3.1. Aktualizujte POM

Najskôr pridajme H2 ako závislosť:

 com.h2database h2 1.4.196 

Môžeme znova skontrolovať najnovšiu verziu ovládača dostupného v Maven Central. Ako sme už vysvetlili, pridali sme tiež doplnok Flyway.

3.2. Nakonfigurujte Flyway pomocou externého súboru

Ďalej tvoríme myFlywayConfig.properties v $ PROJECT_ROOT s nasledujúcim obsahom:

flyway.user = databaseUser flyway.password = databasePassword flyway.schemas = app-db flyway.url = jdbc: h2: mem: DATABASE flyway.locations = súborový systém: db / migrácia

Vyššie uvedená konfigurácia určuje, že naše migračné skripty sú umiestnené v db / migrácia adresár. Pripojí sa k inštancii H2 pomocou užívateľ databázy a heslo do databázy.

Schéma databázy aplikácií je app-db.

Samozrejme, vymieňame flyway.user, flyway.password, a flyway.url s vlastným používateľským menom databázy, heslom databázy a adresou URL databázy zodpovedajúcim spôsobom.

3.3. Definujte prvú migráciu

Flyway dodržiava nasledujúcu konvenciu pomenovania migračných skriptov:

__. sql

Kde:

  • - Predvolená predvoľba je V., ktoré je možné nakonfigurovať vo vyššie uvedenom konfiguračnom súbore pomocou flyway.sqlMigrationPrefix nehnuteľnosť.
  • - Číslo verzie migrácie. Hlavné a vedľajšie verzie môžu byť oddelené znakom podčiarknutie. Verzia migrácie by mala vždy začínať číslom 1.
  • - Textový popis migrácie. Popis je potrebné oddeliť od čísel verzií dvojitým podčiarknutím.

Príklad: V1_1_0__my_first_migration.sql

Poďme teda vytvoriť adresár db / migrácia v $ PROJECT_ROOT s migračným skriptom s názvom V1_0__create_employee_schema.sql obsahujúca inštrukcie SQL na vytvorenie tabuľky zamestnancov:

VYTVORIŤ TABUĽKU, AK NEEXISTUJE `zamestnanec` (` id` int NIE NULL PRIMÁRNY KLÍČ AUTO_INCREMENT, `name` varchar (20),` email` varchar (50), `date_of_birth` timestamp) ENGINE = InnoDB DEFAULT CHARSET = UTF8;

3.4. Vykonajte migrácie

Ďalej vyvoláme nasledujúci príkaz Maven z $ PROJECT_ROOT na vykonanie migrácie databázy:

$ mvn clean flyway: migrate -Dflyway.configFile = myFlywayConfig.properties

To by malo viesť k našej prvej úspešnej migrácii.

Databázová schéma by teraz mala byť zobrazená takto:

zamestnanec: + ---- + ------ + ------- + --------------- + | id | meno | e-mail | dátum_rodenia + ---- + ------ + ------- + --------------- +

Môžeme opakovať kroky definície a vykonania, aby sme vykonali viac migrácií.

3.5. Definujte a vykonajte druhú migráciu

Pozrime sa, ako vyzerá druhá migrácia, vytvorením druhého migračného súboru s názvom V2_0_create_department_schema.sql obsahuje nasledujúce dva dotazy:

VYTVORIŤ TABUĽKU AK NIE JE EXISTUJE `department` (` id` int NOT NULL AUTO_INCREMENT PRIMARY KEY, `name` varchar (20)) ENGINE = InnoDB DEFAULT CHARSET = UTF8; ALTER TABLE `employee` ADD` dept_id` int AFTER `email`;

Vykonáme podobnú migráciu, ako sme to urobili prvýkrát.

A teraz sa naša databázová schéma zmenila a pridala do nej nový stĺpec zamestnanec a nová tabuľka:

zamestnanec: + ---- + ------ + ------- + --------- + --------------- + | id | meno | e-mail | dept_id | dátum_rodenia + ---- + ------ + ------- + --------- + --------------- +
oddelenie: + ---- + ------ + | id | meno | + ---- + ------ +

Teraz môžeme overiť, že obe migrácie boli skutočne úspešné, a to vyvolaním nasledujúceho príkazu Maven:

$ mvn flyway: info -Dflyway.configFile = myFlywayConfig.properties

4. Zakázanie Flyway v Spring Boot

Niekedy možno budeme musieť za určitých okolností deaktivovať migráciu Flyway.

Napríklad je bežnou praxou generovať databázovú schému na základe entít počas testov. V takejto situácii môžeme Flyway deaktivovať pod test profilu.

Pozrime sa aké ľahké je to v Spring Boot.

4.1. Jarná topánka 1.x

Všetko, čo musíme urobiť, je urobiť nastaviť flyway.enabled majetok v našom application-test.properties spis:

flyway.enabled = false

4.2. Jarná topánka 2.x

V novších verziách Spring Boot, táto vlastnosť bola zmenená na pružina:

spring.flyway.enabled = false

4,3 Prázdne FlywayMigrationStrategy

Keby sme len chceli zakázať automatickú migráciu Flyway pri štarte, stále však bude môcť migráciu spustiť manuálne, potom použitie vlastností popísaných vyššie nie je dobrá voľba.

Je to preto, že v takejto situácii Spring Boot nebude automaticky konfigurovať Flyway fazuľa už. Preto by sme si ho museli zabezpečiť sami, čo nie je veľmi výhodné.

Takže ak je toto náš prípad použitia, môžeme nechať Flyway povolený a implementovať prázdny FlywayMigrationStrategy:

@Configuration verejná trieda EmptyMigrationStrategyConfig {@Bean public FlywayMigrationStrategy flywayMigrationStrategy () {return flyway -> {// neurobiť nič}; }}

Toto bude efektívne zakázať migráciu Flyway pri štarte aplikácie.

Stále však budeme môcť migráciu spustiť manuálne:

@RunWith (SpringRunner.class) @SpringBootTest verejná trieda ManualFlywayMigrationIntegrationTest {@Autowired private Flyway flyway; @Test public void skipAutomaticAndTriggerManualFlywayMigration () {flyway.migrate (); }}

5. Ako Flyway funguje

Ak chcete sledovať, ktoré migrácie už boli použité, kedy a kým, pridá do vašej schémy špeciálnu účtovnú tabuľku. Táto tabuľka metadát tiež sleduje kontrolné súčty migrácie a to, či boli migrácie úspešné alebo nie.

Rámec vykonáva nasledujúce kroky, aby vyhovel vyvíjajúcim sa databázovým schémam:

  1. Skontroluje databázovú schému a vyhľadá jej tabuľku metadát (SCHEMA_VERSION predvolene). Ak tabuľka metadát neexistuje, vytvorí ju
  2. Vyhľadáva dostupnú migráciu triedy cesty aplikácie
  3. Porovnáva migrácie s tabuľkou metadát. Ak je číslo verzie menšie alebo rovnaké ako verzia označená ako aktuálna, bude ignorovaná
  4. Označuje všetky zostávajúce migrácie ako nespracované migrácie. Sú zoradené podľa čísla verzie a sú vykonávané v poradí
  5. Keď sa použije každá migrácia, tabuľka metadát sa zodpovedajúcim spôsobom aktualizuje

6. Príkazy

Flyway podporuje nasledujúce základné príkazy na správu migrácií databáz.

  • Info: Vypíše aktuálny stav / verziu schémy databázy. Vytlačí, ktoré migrácie čakajú, ktoré migrácie boli použité, aký je stav aplikovaných migrácií a kedy boli použité.
  • Migrovať: Migruje databázovú schému na aktuálnu verziu. Naskenuje dostupnú migráciu cesty triedy a použije čakajúce migrácie.
  • Východisková hodnota: Vychádza z existujúcej databázy, s výnimkou všetkých migrácií vrátane baselineVersion. Baseline pomáha začať s Flyway v existujúcej databáze. Novšie migrácie je potom možné použiť normálne.
  • Potvrdiť: Validuje aktuálnu databázovú schému proti dostupným migráciám.
  • Oprava: Opravuje tabuľku metadát.
  • Vyčistiť: Spustí všetky objekty v nakonfigurovanej schéme. Všetky databázové objekty sú zrušené. Samozrejme, nikdy by ste nemali používať clean na žiadnej produkčnej databáze.

7. Záver

V tomto článku sme si ukázali, ako Flyway funguje a ako môžeme pomocou tohto rámca spoľahlivo remodelovať našu databázu aplikácií.

Kód sprevádzajúci tento článok je k dispozícii na GitHub.


$config[zx-auto] not found$config[zx-overlay] not found