Capítulo 4: Migración con Liquibase

Introducción

Liquibase es una alternativa popular a Flyway. Mientras que Flyway utiliza principalmente SQL puro, Liquibase ofrece un formato agnóstico de base de datos (XML, YAML, JSON) que puede convertirse en SQL para diferentes bases de datos.

🎯 Objetivos del Capítulo

Al final de este capítulo, usted sabrá:

✅ Comprender las diferencias entre Flyway y Liquibase
✅ Configurar Liquibase con Spring Boot
✅ Crear changelogs en XML, YAML y SQL
✅ Utilizar rollbacks automáticos
✅ Elegir entre Flyway y Liquibase

1. Flyway vs Liquibase

Comparación Rápida

Aspecto	Flyway	Liquibase
Formato principal	SQL nativo	XML, YAML, JSON, SQL
Curva de aprendizaje	Muy fácil	Media
Portabilidad multi-BDD	Baja (SQL específico)	Alta
Rollback	Manual	Automático para algunas operaciones
Comunidad	Muy grande	Grande
Spring Boot	Excelente integración	Excelente integración

¿Cuándo Elegir Flyway?

✅ Use Flyway si:

Utiliza una sola base de datos
Prefiere el SQL nativo
Quiere la máxima simplicidad
Su equipo domina SQL

¿Cuándo Elegir Liquibase?

✅ Use Liquibase si:

Debe soportar varias bases de datos (PostgreSQL, MySQL, Oracle...)
Quiere rollbacks automáticos
Prefiere formatos declarativos (YAML, XML)
Tiene cambios complejos que gestionar

2. Instalación

Dependencia Maven

<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

precaución

Atención: ¡No utilice Flyway y Liquibase juntos en el mismo proyecto!

3. Estructura de Archivos

Estructura Recomendada

src/
└── main/
    └── resources/
        └── db/
            └── changelog/
                ├── db.changelog-master.xml    # Archivo principal
                ├── changes/
                │   ├── 001-create-users.xml
                │   ├── 002-add-email.xml
                │   └── 003-create-orders.xml
                └── data/
                    └── initial-data.xml       # Datos iniciales

Archivo Master (Punto de Entrada)

<!-- db.changelog-master.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <!-- Incluir los archivos de cambios -->
    <include file="db/changelog/changes/001-create-users.xml"/>
    <include file="db/changelog/changes/002-add-email.xml"/>
    <include file="db/changelog/changes/003-create-orders.xml"/>
    
    <!-- O incluir toda una carpeta -->
    <includeAll path="db/changelog/data/"/>

</databaseChangeLog>

4. Formato XML

Crear una Tabla

<!-- 001-create-users.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <changeSet id="1" author="dev">
        <comment>Crear la tabla users</comment>
        
        <createTable tableName="users">
            <column name="id" type="BIGINT" autoIncrement="true">
                <constraints primaryKey="true" nullable="false"/>
            </column>
            <column name="username" type="VARCHAR(50)">
                <constraints nullable="false" unique="true"/>
            </column>
            <column name="password" type="VARCHAR(100)">
                <constraints nullable="false"/>
            </column>
            <column name="created_at" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP"/>
        </createTable>
        
        <!-- Rollback automático: DROP TABLE users -->
    </changeSet>

</databaseChangeLog>

Agregar una Columna

<!-- 002-add-email.xml -->
<databaseChangeLog ...>

    <changeSet id="2" author="dev">
        <comment>Agregar la columna email</comment>
        
        <addColumn tableName="users">
            <column name="email" type="VARCHAR(100)">
                <constraints unique="true"/>
            </column>
        </addColumn>
        
        <!-- Rollback automático: DROP COLUMN email -->
    </changeSet>

</databaseChangeLog>

Crear un Índice

<changeSet id="3" author="dev">
    <createIndex tableName="users" indexName="idx_users_email">
        <column name="email"/>
    </createIndex>
</changeSet>

Insertar Datos

<changeSet id="4" author="dev">
    <insert tableName="users">
        <column name="username" value="admin"/>
        <column name="password" value="$2a$10$hashedpassword"/>
        <column name="email" value="admin@example.com"/>
    </insert>
    
    <!-- Rollback manual necesario -->
    <rollback>
        DELETE FROM users WHERE username = 'admin';
    </rollback>
</changeSet>

5. Formato YAML

¡Mucho más legible que XML!

Crear una Tabla

# 001-create-users.yaml
databaseChangeLog:
  - changeSet:
      id: 1
      author: dev
      comment: Crear la tabla users
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: BIGINT
                  autoIncrement: true
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: username
                  type: VARCHAR(50)
                  constraints:
                    nullable: false
                    unique: true
              - column:
                  name: password
                  type: VARCHAR(100)
                  constraints:
                    nullable: false
              - column:
                  name: created_at
                  type: TIMESTAMP
                  defaultValueComputed: CURRENT_TIMESTAMP

Agregar una Columna

# 002-add-email.yaml
databaseChangeLog:
  - changeSet:
      id: 2
      author: dev
      comment: Agregar email a users
      changes:
        - addColumn:
            tableName: users
            columns:
              - column:
                  name: email
                  type: VARCHAR(100)
                  constraints:
                    unique: true

Archivo Master en YAML

# db.changelog-master.yaml
databaseChangeLog:
  - include:
      file: db/changelog/changes/001-create-users.yaml
  - include:
      file: db/changelog/changes/002-add-email.yaml
  - includeAll:
      path: db/changelog/data/

6. Formato SQL (Como Flyway)

También puede utilizar SQL puro:

-- 001-create-users.sql
-- liquibase formatted sql

-- changeset dev:1
-- comment: Crear la tabla users
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- rollback DROP TABLE users;

-- 002-add-email.sql
-- liquibase formatted sql

-- changeset dev:2
ALTER TABLE users ADD COLUMN email VARCHAR(100) UNIQUE;

-- rollback ALTER TABLE users DROP COLUMN email;

7. Configuración Spring Boot

Configuración Mínima

# application.properties
spring.liquibase.enabled=true
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.xml

Configuración Completa

# Activar Liquibase
spring.liquibase.enabled=true

# Archivo principal de changelog
spring.liquibase.change-log=classpath:db/changelog/db.changelog-master.yaml

# Esquemas
spring.liquibase.default-schema=public
spring.liquibase.liquibase-schema=public

# Contextos (dev, test, prod)
spring.liquibase.contexts=dev

# Labels
spring.liquibase.labels=

# Rollback si falla
spring.liquibase.rollback-file=rollback.sql

Formato YAML

spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml
    default-schema: public
    contexts: dev

8. Rollbacks

Rollback Automático

Liquibase genera automáticamente los rollbacks para:

Operación	Rollback Automático
createTable	DROP TABLE
addColumn	DROP COLUMN
createIndex	DROP INDEX
addForeignKey	DROP FOREIGN KEY
insert	❌ (manual)
update	❌ (manual)
delete	❌ (manual)
sql	❌ (manual)

Rollback Manual

<changeSet id="5" author="dev">
    <update tableName="users">
        <column name="status" value="ACTIVE"/>
        <where>status IS NULL</where>
    </update>
    
    <!-- Rollback manual obligatorio -->
    <rollback>
        <update tableName="users">
            <column name="status" valueComputed="NULL"/>
            <where>status = 'ACTIVE'</where>
        </update>
    </rollback>
</changeSet>

Ejecutar un Rollback

# Rollback del último changeset
mvn liquibase:rollback -Dliquibase.rollbackCount=1

# Rollback hasta un tag
mvn liquibase:rollback -Dliquibase.rollbackTag=v1.0

# Rollback hasta una fecha
mvn liquibase:rollback -Dliquibase.rollbackDate=2025-01-01

9. Contextos y Labels

Contextos

Ejecutar ciertos changesets solo en ciertos entornos:

<!-- Solo en dev -->
<changeSet id="10" author="dev" context="dev">
    <insert tableName="users">
        <column name="username" value="testuser"/>
    </insert>
</changeSet>

<!-- Solo en prod -->
<changeSet id="11" author="dev" context="prod">
    <insert tableName="config">
        <column name="key" value="feature.flag"/>
        <column name="value" value="true"/>
    </insert>
</changeSet>

# application-dev.properties
spring.liquibase.contexts=dev

# application-prod.properties
spring.liquibase.contexts=prod

Labels

Agrupar changesets por funcionalidad:

<changeSet id="20" author="dev" labels="user-feature">
    <!-- Cambios relacionados con usuarios -->
</changeSet>

<changeSet id="21" author="dev" labels="order-feature">
    <!-- Cambios relacionados con pedidos -->
</changeSet>

10. La Tabla DATABASECHANGELOG

Liquibase rastrea los cambios en una tabla:

SELECT * FROM DATABASECHANGELOG;

ID	AUTHOR	FILENAME	DATEEXECUTED	ORDEREXECUTED	EXECTYPE	MD5SUM	DESCRIPTION
1	dev	001-create-users.xml	2025-01-15	1	EXECUTED	abc123	createTable tableName=users
2	dev	002-add-email.xml	2025-01-15	2	EXECUTED	def456	addColumn tableName=users

11. Comandos Maven

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <configuration>
        <propertyFile>src/main/resources/liquibase.properties</propertyFile>
    </configuration>
</plugin>

# Ver el estado
mvn liquibase:status

# Aplicar los cambios
mvn liquibase:update

# Generar el SQL sin ejecutarlo
mvn liquibase:updateSQL

# Rollback
mvn liquibase:rollback -Dliquibase.rollbackCount=1

# Crear un tag
mvn liquibase:tag -Dliquibase.tag=v1.0

# Generar un changelog a partir de una base de datos existente
mvn liquibase:generateChangeLog

12. Resumen

Puntos Clave

Concepto	Descripción
ChangeLog	Archivo principal que lista los cambios
ChangeSet	Un cambio atómico (id + autor único)
Contextos	Filtrar los changesets por entorno
Labels	Agrupar los changesets por funcionalidad
Rollback	Revertir los cambios (auto o manual)

¿Cuándo Usar Cada Herramienta?

Configuración Mínima

# application.yml con Liquibase
spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/db.changelog-master.yaml

Archivo Master Mínimo

# db.changelog-master.yaml
databaseChangeLog:
  - includeAll:
      path: db/changelog/changes/

🎯 Próximo Paso

¡Ahora tiene toda la teoría! Es momento de practicar con los ejercicios prácticos.

➡️ TP7.1: Configuración Datasource y Pool

⬅️ Volver al Módulo 7

Introducción​

🎯 Objetivos del Capítulo​

1. Flyway vs Liquibase​

Comparación Rápida​

¿Cuándo Elegir Flyway?​

¿Cuándo Elegir Liquibase?​

2. Instalación​

Dependencia Maven​

3. Estructura de Archivos​

Estructura Recomendada​

Archivo Master (Punto de Entrada)​

4. Formato XML​

Crear una Tabla​

Agregar una Columna​

Crear un Índice​

Insertar Datos​

5. Formato YAML​

Crear una Tabla​

Agregar una Columna​

Archivo Master en YAML​

6. Formato SQL (Como Flyway)​

7. Configuración Spring Boot​

Configuración Mínima​

Configuración Completa​

Formato YAML​

8. Rollbacks​

Rollback Automático​

Rollback Manual​

Ejecutar un Rollback​

9. Contextos y Labels​

Contextos​

Labels​

10. La Tabla DATABASECHANGELOG​

11. Comandos Maven​

12. Resumen​

Puntos Clave​

¿Cuándo Usar Cada Herramienta?​

Configuración Mínima​

Archivo Master Mínimo​

🎯 Próximo Paso​

Introducción

🎯 Objetivos del Capítulo

1. Flyway vs Liquibase

Comparación Rápida

¿Cuándo Elegir Flyway?

¿Cuándo Elegir Liquibase?

2. Instalación

Dependencia Maven

3. Estructura de Archivos

Estructura Recomendada

Archivo Master (Punto de Entrada)

4. Formato XML

Crear una Tabla

Agregar una Columna

Crear un Índice

Insertar Datos

5. Formato YAML

Crear una Tabla

Agregar una Columna

Archivo Master en YAML

6. Formato SQL (Como Flyway)

7. Configuración Spring Boot

Configuración Mínima

Configuración Completa

Formato YAML

8. Rollbacks

Rollback Automático

Rollback Manual

Ejecutar un Rollback

9. Contextos y Labels

Contextos

Labels

10. La Tabla DATABASECHANGELOG

11. Comandos Maven

12. Resumen

Puntos Clave

¿Cuándo Usar Cada Herramienta?

Configuración Mínima

Archivo Master Mínimo

🎯 Próximo Paso