Liquibase — Cheat Sheet

Tag: liquibase, database, migrations, ci-cd, sql, devops

Livello: intermedio

TL;DR: Strumento open-source per il versioning e refactoring del database. Gestisce le migrazioni tramite changelog dichiarativi e traccia le esecuzioni, garantendo allineamento e riproducibilità tra gli ambienti.

Concetti chiave

Changelog: File radice che elenca in ordine sequenziale tutte le modifiche da applicare al database (supporta XML, YAML, JSON o SQL).

Changeset: Unità atomica di modifica al database (es. creazione tabella), identificata in modo univoco da id e author.

DatabaseChangeLog: Tabella creata automaticamente nel database target per tracciare i changeset già eseguiti e i relativi checksum (MD5).

DatabaseChangeLogLock: Tabella usata per impedire l'esecuzione concorrente delle migrazioni da parte di istanze multiple.

Rollback: Istruzioni per annullare un changeset. Operazioni semplici (come createTable) hanno il rollback automatico, altre richiedono istruzioni custom.

Preconditions: Controlli logici valutati prima di eseguire un changeset (es. verifica che una tabella o colonna esista già per evitare errori).

Contexts: Etichette assegnate ai changeset per limitarne l'esecuzione ad ambienti specifici (es. caricare dati di test solo se context è dev o test).

Checksum: Hash MD5 calcolato sul contenuto del changeset per prevenire modifiche accidentali a migrazioni già applicate.

Domande tipiche e risposte pronte

Q: Come gestisce Liquibase la concorrenza tra nodi multipli durante il deploy?R: Utilizza la tabella DATABASECHANGELOGLOCK. Il primo nodo che si avvia acquisisce il lock impostando il flag a 1. Gli altri nodi in partenza attendono il rilascio.

Q: Qual è la differenza tra usare formati dichiarativi (XML/YAML) e usare SQL puro nei changelog?R: I formati dichiarativi sono database-agnostic. Liquibase traduce il comando nel dialetto SQL del database target e spesso genera il rollback in automatico. Il formato SQL lega il changelog a un RDBMS specifico.

Q: Cosa succede se modifico il file di un changeset già eseguito in produzione?R: Al successivo avvio, Liquibase calcolerà un nuovo checksum, lo confronterà con quello salvato in tabella e andrà in errore bloccando il deploy per "checksum validation failed".

Q: Come si sblocca un lock rimasto appeso dopo un crash del processo di migrazione?R: Eseguendo il comando liquibase releaseLocks da CLI o, manualmente, facendo un UPDATE DATABASECHANGELOGLOCK SET locked = 0, lockedby = NULL.

Insidie e errori comuni

Modificare un changeset già applicato causando il fallimento della validazione del checksum al successivo rilascio.

Dimenticare di scrivere il blocco <rollback> per operazioni distruttive, script custom SQL o dati di fix, rendendo impossibile fare il downgrade.

Lasciare lock pendenti nel database in caso di crash del container o interruzione della pipeline CI/CD durante la fase di migrazione.

Non configurare l'attributo logicalFilePath nei changelog: se i file vengono spostati in altre directory, il checksum si invalida perché il path del file è parte della chiave.

Snippet e comandi

# Esegue tutte le migrazioni non ancora applicate
liquibase update

# Simula l'esecuzione per visualizzare l'SQL generato senza applicarlo
liquibase updateSQL

# Esegue il rollback dell'ultimo changeset applicato
liquibase rollbackCount 1

# Ricalcola i checksum nella tabella DatabaseChangeLog
liquibase clearCheckSums

XML

<!-- Esempio di changeset in XML con rollback automatico -->
<changeSet id="1" author="umberto">
    <createTable tableName="users">
        <column name="id" type="int">
            <constraints primaryKey="true" nullable="false"/>
        </column>
        <column name="username" type="varchar(50)"/>
    </createTable>
</changeSet>
Jarvis Interviews
Jarvis