Integrazione di Flyway in un'applicazione Spring Framework - Trifork Blog (2023)

Questo post parla di come integrareVola viain un'applicazione Spring/JPA per la migrazione dello schema del database. Per saltare tutti i preamboli e andare direttamente alle istruzioni, vai aConfigurazione delle dipendenze del progetto

Flyway è uno strumento di migrazione del database che aiuta a fare ai database ciò che strumenti come git/svn/mercurial fanno per il codice sorgente... che è il controllo delle versioni. Con Flyway puoi facilmente versionare il tuo database: creare, migrare e accertarne lo stato, la struttura, insieme ai suoi contenuti. Fondamentalmente ti consente di assumere il controllo del tuo database ed essere in grado di ricrearlo in diversi ambienti o diverse versioni dell'applicazione con cui viene eseguito, tenendo traccia delle modifiche cronologiche apportate.

Di recente ho lavorato a un progetto in cui era necessaria tale migrazione dello schema del database. E abbiamo trovato Flyway un buon strumento per il lavoro. Prima di utilizzare Flyway, tutti gli aggiornamenti dello schema che dovevano essere eseguiti venivano consegnati al client in file SQL separati, con istruzioni su come eseguirli.

La breve venuta di un tale processo divenne presto evidente. Era gravoso e soggetto a errori.

Prima di tutto, richiede attività operative extra da parte del cliente in quanto deve eseguire qualsiasi script di aggiornamento fornito e garantire che lo schema del database sia nello stato richiesto prima della distribuzione dell'applicazione: non è un processo ideale. Un'applicazione dovrebbe essere il più autonoma possibile, quindi una volta consegnata, dovrebbe essere distribuibile senza troppi problemi da parte del cliente.

Inoltre espone inutilmente gli interni dello stato del database. La modifica del database al di fuori dell'applicazione non ne garantisce l'integrità, soprattutto quando la modifica del database viene eseguita da una parte che non è a conoscenza degli interni dell'applicazione con cui è in esecuzione il database.

Pertanto, quando è arrivato il momento di aggiornare la versione dell'applicazione in produzione a una versione più recente, abbiamo deciso di rivalutare il processo attraverso il quale forniamo gli aggiornamenti dello schema. Questo è quando Flyway è entrato in scena.

Come accennato, Flyway è uno strumento di migrazione del database. Può essere utilizzato tramite il suo strumento da riga di comando, tramite un plug-in Maven o un alleato programmatico dall'interno di un'applicazione, ma poiché l'applicazione su cui stavo lavorando è stata creata con il framework Spring e utilizza un database supportato da JPA (fornito da Hibernate) , ho quindi deciso di integrare Flyway in un'applicazione di questo tipo. Questo post cattura il passaggio tipico che sarebbe coinvolto.

Ma prima di entrare nei passaggi, una piccola panoramica di come funziona Flyway aiuterebbe ad avere una chiara comprensione delle istruzioni di integrazione.

Come funziona Flyway. Una panoramica

Le modifiche dello schema e la modifica del contenuto (aggiunta, modifica o eliminazione del contenuto nelle tabelle del database) vengono eseguite tramite istruzioni SQL. Ciò che Flyway fa è fornire un meccanismo in cui queste modifiche possono essere registrate e versionate. Lo fa 1) essendo responsabile dell'applicazione delle modifiche allo schema specificate negli script SQL e 2) mantenendo una tabella di metadati interna denominata SCHEMA_VERSION attraverso la quale tiene traccia di varie informazioni riguardanti gli script applicati: quando è stato applicato, da chi è stato applicato, descrizione della migrazione applicata, il suo numero di versione ecc.

Flyway consente di fornire gli script SQL (spesso indicati come migrazioni) sotto forma di semplici vecchi file di script SQL o tramite codice Java. La cosa importante, però, è che, qualunque forma sia scritta la migrazione, i file devono essere nominati seguendo una convenzione, che viene spiegatasotto.

Per ulteriori informazioni su come funziona Flyway, controlla ilCome funziona Flywaynel sito web del progetto.

Ora con la breve panoramica fuori mano, possiamo andare avanti e guardare le istruzioni.

Integrazione di Flyway in un'applicazione JPA supportata da Spring.

Quando si integra Flyway in un'applicazione JPA, Spring, ciò che si desidera fare è avviare Flyway, trovare i file di migrazione (in SQL o JAVA) e applicare le modifiche necessarie al database all'avvio dell'applicazione. I seguenti passaggi mostrano come raggiungere questo obiettivo.

1. Configurazione delle dipendenze del progetto

La prima cosa da fare è aggiungere le necessarie dipendenze del progetto, quindi a parte le dipendenze Spring/JPA, includere Flyway come dipendenza. Se stai usando Maven, le seguenti righe dovrebbero essere aggiunte alla sezione delle dipendenze del tuo POM.xml:

 org.flywaydb flyway-core ${Flyway.version}

Nel caso in cui non utilizzi Maven per la gestione delle dipendenze, il processo di inclusione di Flyway dovrebbe essere banale in qualunque strumento tu stia utilizzando.

2. Configurazione di Flyway per l'integrazione nel contenitore di Spring

I passaggi successivi sarebbero la configurazione necessaria per fare in modo che Spring raccolga Flyway come bean gestito e farlo funzionare bene con altri bean di cui avrebbe bisogno per farlo funzionare ... per essere specifici la fabbrica del gestore di entità.

Se stai usando XML per configurare Spring, la configurazione necessaria dovrebbe apparire così:

  < property name="locations" value="filesystem:/path/to/migrations/" />              

Se stai usando JavaConfig su XML, la configurazione apparirà così:

@Configurationpublic class AppConfig {@Bean(initMethod = "migrate")Flyway flyway() {Flyway flyway = new Flyway();flyway.setBaselineOnMigrate(true);flyway.setLocations("filesystem:/path/to/migrations/") ;flyway.setDataSource(dataSource());return flyway;}@Bean @DependsOn("flyway")EntityManagerFactory entityManagerFactory() {LocalContainerEntityManagerFactoryBean bean = new LocalContainerEntityManagerFactoryBean();bean.setDataSource(dataSource());// altre configurazionireturn bean .getObject();}@BeanDataSource dataSource() {DataSource dataSource = new BasicDataSource();// configurazione origine datireturn dataSource;}}

Alcune cose aggiuntive da prendere in considerazione nelle configurazioni:

Configurazione del flyway.
Quando si configura Flyway è necessario specificare il filemetodo init(che è stato fatto usando ilmetodo initproprietà in xml einitMethodproprietà del@Fagioloannotazione in JavaConfig)

Questo è usato per istruire Spring a chiamare ilmigrare()metodo una volta inizializzate tutte le proprietà del bean Flyway. ILmigrare()metodo è ciò che è responsabile dell'esecuzione della logica di migrazione: ovvero trovare gli script di migrazione, applicarli e tenere una scheda delle migrazioni riuscite ecc. Ecco perché è specificato come metodo init poiché vorresti che fosse eseguito non appena il bean Flyway viene inizializzato nel contenitore di Spring.

ILbaseLineOnMigrateè anche un'altra parte interessante della configurazione. È utile quando Flyway viene inizialmente utilizzato per la prima volta e non esiste alcuna tabella SCHEMA_VERSION. Indica a Flyway che prima dell'applicazione degli script di migrazione, dovrebbe creare una voce di migrazione all'interno della tabella SCHEMA_VERSION che fungerebbe da linea di base, e quindi lo script di migrazione disponibile verrebbe applicato solo se la loro versione è superiore alla versione di base.

ILfonte di dativiene utilizzato per specificare il dataSource. Niente di interessante in questo.

L'ultimo elemento di interesse nella configurazione è il fileposizioneattraverso il quale si specifica dove Flyway deve trovare gli script di migrazione. Flyway ha la capacità di scansionare il filesystem o il classpath per questi script di migrazione. Nell'esempio precedente il valore assegnato alla posizione è preceduto da "filesystem:” indicando a Flyway di utilizzare il suo scanner di file system per individuare gli script di migrazione. Se non viene specificato alcun prefisso o "percorso di classe:" viene utilizzato come prefisso, quindi Flyway utilizza il suo scanner classloader per individuare gli script di migrazione.

Configurazione di fabbrica di Entity Manager.

L'unica cosa da prendere in considerazione nella configurazione di Entity Manager Factory è ildipende daproprietà impostata per fare riferimento al bean Flyway. Ciò che fa è garantire che il bean Flyway venga sempre creato prima del bean Entity Manager Factory. Che è quello che vorresti dato che Flyway è già stato creato, fai il suo lavoro prima che Entity Manager Factory entri in azione. In JavaConfig questo è specificato usando il@Dipende daannotazione.

3. Scrivere script di migrazione

Ora che hai configurato i bean necessari, la prossima cosa da fare è creare gli script di migrazione che contengono gli aggiornamenti dello schema necessari che devono essere applicati al database durante una migrazione. Come specificato in precedenza, Flyway supporta gli script di migrazione scritti in semplice vecchio SQL o in Java.

Qualunque sia il metodo utilizzato, tutto ciò che devi fare è avere i file di migrazione nominati in modo appropriato, seguendo la convenzione richiesta da Flyway e averli nella posizione specificata nella configurazione.

Perché una convenzione di denominazione? La convenzione di denominazione è richiesta, poiché questo è il modo predefinito in cui Flyway tiene traccia del suo versioning (dico predefinito perché quando si utilizza Java, c'è la possibilità di ignorare questo meccanismo di denominazione. Questo è spiegato di seguito). Lo utilizza per determinare l'ordine in cui devono essere applicati gli script di migrazione e per tenere traccia degli script applicati e di quelli in attesa.

La convenzione di denominazione è la seguente:

V__.

Doveè un valore numerico che può contenere un punto (“.”) o un trattino basso (“_”) ad esempio 3, 3.1, 3_1 sono tutti validi per la versione. (Non che se viene utilizzato un carattere di sottolineatura, verrebbe trasformato in un punto "." in fase di esecuzione da Flyway)

La doppia sottolineatura,__è ciò che viene utilizzato per separare il numero di versione dalla descrizione.

è una breve descrizione di cosa trattano gli script contenuti nel file. Verrebbe estratto e aggiunto alla colonna della descrizione della tabella schema_version.

Per il,puoi avere sql o java a seconda del metodo utilizzato per fornire le migrazioni.

Quindi i seguenti sono tutti nomi validi

V3__description_of_migration.sql
V3.1__description_of_migration .java
V3_1__description_of_migration .sql

Se le migrazioni sono specificate in SQL, c'è poco altro che può essere fatto oltre a specificare gli aggiornamenti dello schema e denominarli in modo appropriato. D'altra parte, con Java abbiamo un po' più di flessibilità. Darei rapidamente un'occhiata a come utilizzare Java per scrivere la migrazione e alcune delle sue funzionalità disponibili non presenti quando si utilizza SQL.

3. Scrivere la migrazione Flyway in Java.

Come per la migrazione scritta in SQL, è necessario disporre della migrazione Java nella posizione specificata nella configurazione. È quindi necessario che la classe in cui è scritta la migrazione sql implementi il ​​fileMigrazione JdbcOSpringJdbcMigrationinterfaccia.

La differenza tra queste due interfacce è chejdbcMigrationFai unConnessioneoggetto disponibile per interagire con il database whileSpringJdbcMigrationFai unModello Jdbcoggetto disponibile per l'interazione con il database.

Quindi uno script di migrazione scritto in Java potrebbe assomigliare a questo:

import org.flywaydb.core.api.migration.spring.SpringJdbcMigration;import org.springframework.jdbc.core.JdbcTemplate;public class V2__moveDBStateToV2 implementa SpringJdbcMigration {@Overridepublic void migrate(JdbcTemplate jdbcTemplate) genera un'eccezione {// modifica a livello di codice lo stato del database usando JdbCTemplate}}

E questo è tutto. In questo modo è possibile eseguire controlli complessi e operazioni necessarie per spostare lo stato del database in uno stato richiesto.

Oltre a ciò, l'opzione Java fornisce anche alcune funzionalità aggiuntive come consentire di ignorare la convenzione di denominazione e avere invece la versione e la descrizione specificate nella classe Java. Questo viene fatto implementando ilMigrationInfoProviderInterfaccia. Per esempio:

public class WhateverName implementa SpringJdbcMigration, MigrationInfoProvider {@Overridepublic void migrate(JdbcTemplate jdbcTemplate) throws Exception {// modifica programmatica dello stato del database utilizzando JdbCTemplate}@Overridepublic MigrationVersion getVersion() {return MigrationVersion.fromVersion("2"); //return 2 as version}@Overridepublic String getDescription() {return "Sposta il DB nello stato due";}}

Alcuni pensieri di chiusura.

Quando mi sono avvicinato per la prima volta a Flyway come strumento da utilizzare per la migrazione del database, uno dei primi pensieri che mi è venuto in mente è stato perché utilizzare uno strumento quando ho già ibernato hbm2ddl che può essere utilizzato anche per modificare lo schema del database. Ho già Hibernate come provider JPA, perché uno strumento esterno?

La risposta è semplice. Hibernates hbm2ddl non è in alcun modo flessibile o potente rispetto a uno strumento di migrazione del database come Flyway. Fondamentalmente, hbm2ddl potrebbe essere visto solo come uno strumento per estendere il database per mantenerlo in linea con le nuove aggiunte all'entità di supporto. Non ha la possibilità di modificare i nomi dei campi, trasferire i dati da una colonna all'altra, ecc. Attività che compaiono sempre in qualsiasi situazione di migrazione del database nella vita reale.

Quindi, se hai bisogno di eseguire correttamente la migrazione e il controllo delle versioni del database, uno strumento come Flyway è abbastanza utile.

Una cosa da notare è che Flyway può essere utilizzato come strumento di migrazione autonomo. Ciò è possibile tramite il robusto strumento a riga di comando di Flyway, le cui istruzioni possono essere trovateQui. Flyway fornisce anche callback che possono essere utilizzati come punti di estensione per agganciarsi al ciclo di vita di Flyway per eseguire operazioni avanzate. Le istruzioni sulla richiamata possono essere trovateQui.

Tutto sommato, Flyway brilla davvero in quanto fa il lavoro e lo fa bene. È relativamente semplice con poca curva di apprendimento e flessibile. Anche la documentazione e JavaDoc sono decenti, il che rende il lavoro indolore.