Flyway — Cheat Sheet

Tag: flyway, database, migrations, sql, devops, java, backend

Livello: intermedio

TL;DR: Strumento di database migration a controllo di versione basato su script SQL o Java; applica modifiche incrementali e traccia lo stato del DB via tabella schema history.

Concetti chiave

Gestisce l'evoluzione dello schema di database tramite migrazioni versionate e ripetibili.

Traccia l'esecuzione e lo stato degli script nella tabella interna flyway_schema_history.

Calcola un checksum per ogni script versionato per garantire l'immutabilità delle modifiche applicate.

Script versionati (V): eseguiti una sola volta in ordine strettamente progressivo di versione.

Script ripetibili (R): eseguiti ogni volta che il loro checksum cambia, sempre dopo i versionati.

Script di rollback (U): supportano l'operazione di undo, disponibili con licenza Flyway Teams/Enterprise.

Comandi principali: migrate, clean, info, validate, baseline, repair.

Supporta migrazioni basate su plain SQL oppure implementazioni programmatiche in Java.

Domande tipiche e risposte pronte

Q: A cosa serve Flyway e come garantisce che una migrazione non venga rieseguita o alterata?R: Flyway applica modifiche sequenziali al database leggendo script ordinati per versione. Salva nella tabella flyway_schema_history versione, data e checksum dello script: se un file già applicato viene modificato, la validazione fallisce immediatamente segnalando un mismatch nel checksum.

Q: Che differenza c'è tra versioned migration e repeatable migration?R: Le versioned migration hanno un prefisso di versione (es. V1__init.sql) e vengono eseguite una sola volta; le repeatable migration (es. R__views.sql) non hanno versione e vengono rieseguite in ordine alfabetico ogni volta che il loro checksum cambia.

Q: Cosa succede se una migrazione fallisce su un database non transazionale DDL?R: Se il DB non supporta DDL atomico, la migrazione si blocca a metà lasciando lo stato marcato come failed in flyway_schema_history; occorre correggere manualmente lo schema DB e lanciare flyway repair prima di rieseguire flyway migrate.

Insidie e errori comuni

Modificare uno script versionato già applicato in un ambiente condiviso, provocando errore di checksum mismatch.

Mancato supporto DDL transazionale (es. MySQL prima della 8.0 o Oracle per certi statement), che lascia tabelle parziali in caso di errore.

Errore nella convenzione dei nomi file: servono due underscore tra versione e descrizione (es. V1_2__name.sql, non un singolo underscore).

Eseguire migrazioni lunghe o blocchi DDL esclusivi in fase di bootstrap dell'applicazione producendo timeout all'avvio.

Snippet e comandi

# Esecuzione migrazioni verso l'ultima versione disponibile
flyway migrate

# Verifica stato delle migrazioni e confronto con la history table
flyway info

# Valida che i file locali corrispondano ai checksum applicati sul DB
flyway validate

# Ripara la history table rimuovendo entry fallite o riallineando checksum
flyway repair

# Imposta una baseline per database preesistenti non partiti da vuoto
flyway baseline -baselineVersion=1.0 -baselineDescription="Initial baseline"

SQL

```-- Esempio nomenclatura: V1__create_users_table.sql

CREATE TABLE users (

id BIGINT PRIMARY KEY AUTO_INCREMENT,

email VARCHAR(255) NOT NULL UNIQUE,

created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP

);

-- Esempio nomenclatura: R__user_summary_view.sql

CREATE OR REPLACE VIEW user_summary AS

SELECT id, email, created_at FROM users;

```

Da ripassare

[ ] Meccanismo e parametri di flyway baseline per l'adozione su schemi preesistenti

[ ] Differenze tra flyway community e comandi proprietari (es. undo)

[x] Regole di naming convention per script versionati (V), undo (U) e ripetibili (R)

[x] Risoluzione errori di checksum mismatch con flyway repair