Databaseoverføringer med Flyway

1. Introduksjon

Denne artikkelen beskriver sentrale begreper Flyway og hvordan vi kan bruke dette rammeverket til kontinuerlig ombygging av applikasjonens databaseskjema pålitelig og enkelt. På slutten presenterer vi et eksempel på administrering av en H2-database i minnet ved hjelp av et Maven Flyway-plugin.

Flyway oppdaterer en database fra en versjon til en annen ved hjelp av migrasjoner. Vi kan skrive migrasjoner enten i SQL med databasespesifikk syntaks eller i Java for avanserte databasetransformasjoner.

Overføringer kan enten versjoneres eller repeteres. Førstnevnte har en unik versjon og brukes nøyaktig en gang. Sistnevnte har ingen versjon. I stedet blir de brukt på nytt hver gang kontrollsummen endres.

Innen en enkelt migreringskjøring blir repeterbare migreringer alltid brukt sist, etter at versjonerte migrasjoner er utført. Gjentakbare migrasjoner brukes i rekkefølge etter beskrivelsen. For en enkelt migrering kjøres alle utsagn i en enkelt databasetransaksjon.

I denne artikkelen fokuserer vi hovedsakelig på hvordan vi kan bruke Maven-pluginet til å utføre databasemigrasjoner.

2. Flyway Maven-plugin

For å installere et Flyway Maven-plugin, la oss legge til følgende plugin-definisjon i vår pom.xml:

 org.flywaydb flyway-maven-plugin 4.0.3

Vi kan sjekke den nyeste versjonen av programtillegget tilgjengelig på Maven Central.

Dette Maven-pluginet kan konfigureres på fire forskjellige måter. Se dokumentasjonen for å få en liste over alle konfigurerbare egenskaper.

2.1. Plugin-konfigurasjon

Vi kan konfigurere programtillegget direkte via tag i plugin-definisjonen av vår pom.xml:

 org.flywaydb flyway-maven-plugin 4.0.3 database Brukerdatabase Passordskjema Navn ...

2.2. Maven Properties

Vi kan også konfigurere programtillegget ved å spesifisere konfigurerbare egenskaper som Maven eiendommer i vår pom:

 ... databaseBrukerdatabasePassordskjemanavn ... ...

2.3. Ekstern konfigurasjonsfil

Vi kan også tilby plugin-konfigurasjon i en separat .eiendommer fil:

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

Standard konfigurasjonsfilnavn er flyway.properties og den skal ligge i samme katalog som pom.xml fil. Koding er spesifisert av flyway.encoding (Standard er UTF-8).

Hvis du bruker et annet navn (f.eks customConfig.properties) som konfigurasjonsfil, bør den spesifiseres eksplisitt når du påkaller Maven-kommandoen:

$ mvn -Dflyway.configFile = customConfig.properties

2.4. System egenskaper

Til slutt kan alle konfigurasjonsegenskaper også spesifiseres som systemegenskaper når de påkaller Maven på kommandolinjen:

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

Følgende er en prioritetsrekkefølge når en konfigurasjon er spesifisert på mer enn én måte:

System egenskaper
Ekstern konfigurasjonsfil
Maven eiendommer
Plugin-konfigurasjon

3. Eksempel på migrasjon

I denne delen går vi gjennom de nødvendige trinnene for å migrere et databaseskjema til en H2-database i minnet ved hjelp av Maven-pluginet. Vi bruker en ekstern fil for å konfigurere Flyway.

3.1. Oppdater POM

La oss først legge til H2 som en avhengighet:

 com.h2database h2 1.4.196

Vi kan igjen sjekke den nyeste versjonen av driveren som er tilgjengelig på Maven Central. Vi vil også legge til Flyway-pluginet som forklart tidligere.

3.2. Konfigurer Flyway ved hjelp av ekstern fil

Deretter lager vi myFlywayConfig.properties i $ PROJECT_ROOT med følgende innhold:

flyway.user = databaseUser flyway.password = databasePassword flyway.schemas = app-db flyway.url = jdbc: h2: mem: DATABASE flyway.locations = filsystem: db / migrasjon

Konfigurasjonen ovenfor spesifiserer at overføringsskriptene våre ligger i db / migrasjon katalog. Den kobles til en H2-forekomst i minnet ved hjelp av databaseUser og databasePassword.

Programskjemaet er app-db.

Selvfølgelig erstatter vi flyway.user, flyway.password, og flyway.url med vårt eget databasens brukernavn, databasepassord og database-URL på riktig måte.

3.3. Definer første migrasjon

Flyway følger følgende navngivningskonvensjon for migrasjonsskript:

__. kvm

Hvor:

- Standard prefiks er V, som kan konfigureres i konfigurasjonsfilen ovenfor ved hjelp av flyway.sqlMigrationPrefix eiendom.
- Migrasjonsversjonsnummer. Store og mindre versjoner kan være atskilt med en understrek. Migrasjonsversjonen skal alltid starte med 1.
- Tekstbeskrivelse av migrasjonen. Beskrivelsen må skilles fra versjonsnumrene med dobbelt understreking.

Eksempel: V1_1_0__my_first_migration.sql

Så la oss lage en katalog db / migrasjon i $ PROJECT_ROOT med et migrasjonsskript som heter V1_0__create_employee_schema.sql inneholder SQL-instruksjoner for å opprette arbeidstabellen:

OPPRETT TABELL HVIS IKKE FINTER `ansatt` (` id` int IKKE NULL AUTO_INCREMENT PRIMARY KEY, `name` varchar (20),` email 'varchar (50), `date_of_birth` tidsstempel) MOTOR = InnoDB STANDARD CHARSET = UTF8;

3.4. Utfør overføringer

Deretter påkaller vi følgende Maven-kommando fra $ PROJECT_ROOT for å utføre databasemigrasjoner:

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

Dette burde resultere i vår første vellykkede migrasjon.

Databaseskjemaet skal nå vises som følger:

ansatt: + ---- + ------ + ------- + --------------- + | id | navn | e-post | fødselsdato | + ---- + ------ + ------- + --------------- +

Vi kan gjenta trinn for definisjon og kjøring for å gjøre flere migrasjoner.

3.5. Definere og utføre andre migrasjon

La oss se hvordan en annen migrering ser ut ved å opprette en annen migreringsfil med navn V2_0_create_department_schema.sql som inneholder følgende to spørsmål:

OPPRETT TABELL HVIS IKKE FUNGER `avdeling '(` id` int IKKE NULL AUTO_INCREMENT PRIMÆR NØKKEL, `navn` varchar (20)) MOTOR = InnoDB STANDARD CHARSET = UTF8; ALTER TABLE `ansatt` LEGG TIL` dept_id` int ETTER `e-post";

Vi vil utføre en lignende migrasjon som vi gjorde første gang.

Og nå er databaseskjemaet vårt endret for å legge til en ny kolonne i ansatt og et nytt bord:

ansatt: + ---- + ------ + ------- + --------- + --------------- + | id | navn | e-post | dept_id | fødselsdato | + ---- + ------ + ------- + --------- + --------------- +

avdeling: + ---- + ------ + | id | navn | + ---- + ------ +

Vi kan nå bekrefte at begge migrasjonene faktisk var vellykkede ved å påkalle følgende Maven-kommando:

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

4. Deaktivere Flyway i Spring Boot

Noen ganger kan det hende vi trenger det deaktivere Flyway-migrasjoner under visse omstendigheter.

For eksempel er det en vanlig praksis å generere databaseskjema basert på enhetene under testene. I en slik situasjon kan vi deaktivere Flyway under test profil.

La oss se hvor lett det er i Spring Boot.

4.1. Spring Boot 1.x

Alt vi trenger å gjøre er å sett flyway. aktivert eiendom i vår applikasjonstest.egenskaper fil:

flyway.enabled = false

4.2. Spring Boot 2.x

I de nyere versjonene av Spring Boot, denne eiendommen er endret til spring.flyway.enabled:

spring.flyway.enabled = false

4.3 Tom FlywayMigrationStrategy

Hvis vi bare vil deaktiver automatisk Flyway-migrering ved oppstart, men fremdeles være i stand til å utløse migreringen manuelt, og bruk av egenskapene beskrevet ovenfor er ikke et godt valg.

Det er fordi Spring Boot ikke vil konfigurere automatisk i en slik situasjon Flyway bønne lenger. Derfor må vi tilby det på egen hånd, noe som ikke er veldig praktisk.

Så hvis dette er vårt brukstilfelle, kan vi la Flyway være aktivert og implementere et tomt FlywayMigrationStrategy:

@Configuration public class EmptyMigrationStrategyConfig {@Bean public FlywayMigrationStrategy flywayMigrationStrategy () {retur flyvebane -> {// gjør ingenting}; }}

Dette vil effektivt deaktiver Flyway-migrering ved oppstart av programmet.

Men vi vil fortsatt kunne utløse migreringen manuelt:

@RunWith (SpringRunner.class) @SpringBootTest offentlig klasse ManualFlywayMigrationIntegrationTest {@Autowired private Flyway flyway; @Test offentlig ugyldig skipAutomaticAndTriggerManualFlywayMigration () {flyway.migrate (); }}

5. Hvordan Flyway fungerer

For å holde oversikt over hvilke migrasjoner som allerede er brukt, når og av hvem, legger det til en spesiell bokføringstabell i skjemaet ditt. Denne metadatatabellen sporer også migrasjonskontrollsummer og om migreringene var vellykkede eller ikke.

Rammeverket utfører følgende trinn for å imøtekomme databaseskjemaer i utvikling:

Den sjekker et databaseskjema for å finne metadatatabellen (SCHEMA_VERSION som standard). Hvis metadatatabellen ikke eksisterer, vil den opprette en
Den skanner en søknadsklasse for tilgjengelige migrasjoner
Den sammenligner migrasjoner mot metadatatabellen. Hvis et versjonsnummer er lavere eller lik en versjon som er merket som nåværende, ignoreres det
Den markerer eventuelle gjenværende migrasjoner som ventende migrasjoner. Disse sorteres etter versjonsnummer og utføres i rekkefølge
Når hver migrering brukes, oppdateres metadatatabellen tilsvarende

6. Kommandoer

Flyway støtter følgende grunnleggende kommandoer for å administrere migrering av databaser.

Info: Skriver ut gjeldende status / versjon av et databaseskjema. Den skriver ut hvilke migrasjoner som er i påvente, hvilke migrasjoner som er brukt, hva er statusen til anvendte migrasjoner og når de ble brukt.
Migrere: Overfører et databaseskjema til den gjeldende versjonen. Den skanner klassestien for tilgjengelige migreringer og bruker ventende migrasjoner.
Grunnlinje: Baserer en eksisterende database, unntatt alle migrasjoner, inkludert baselineVersjon. Baseline hjelper til med å starte med Flyway i en eksisterende database. Nyere migrasjoner kan deretter brukes normalt.
Validere: Validerer gjeldende databaseskjema mot tilgjengelige migrasjoner.
Reparere: Reparerer metadatatabellen.
Ren: Slipper alle objekter i et konfigurert skjema. Alle databaseobjekter blir droppet. Selvfølgelig bør du aldri bruke rent på noen produksjonsdatabase.

7. Konklusjon

I denne artikkelen har vi vist hvordan Flyway fungerer, og hvordan vi kan bruke dette rammeverket til å omforme vår applikasjonsdatabase pålitelig.

Koden som følger med denne artikkelen er tilgjengelig på GitHub.

streamalism.org