Gestión de Migraciones de Base de Datos con Flyway en Spring Boot"

Introducción

El desarrollo de aplicaciones modernas no solo implica escribir código de negocio, sino también gestionar la evolución de la base de datos. A medida que un proyecto crece, mantener la coherencia del esquema entre desarrolladores, ramas y entornos puede volverse complejo.

Aquí es donde Flyway entra en juego: una herramienta de migración de base de datos ligera y poderosa que permite controlar versiones de esquemas de forma segura, repetible y automatizada.

¿Qué es Flyway?

Flyway es una herramienta de migración de base de datos que permite aplicar scripts de manera controlada y automática. Utiliza una convención de nombres para identificar versiones y aplica cambios incrementales cada vez que la aplicación se inicia.

Problemas que resuelve:

• Desincronización entre esquemas de desarrollo, prueba y producción.
• Cambios accidentales o no versionados.
• Dificultad para aplicar migraciones en equipo o CI/CD.
• Fragilidad de los esquemas generados automáticamente por JPA.

Comparación breve con alternativas:

Herramienta	Lenguaje	Comunidad	SQL puro	Migraciones Java
Flyway	Java	Muy activa	✅ Sí	✅ Opcional
Liquibase	Java	Activa	✅ Sí	✅ Más flexible

¿Cuándo usar Flyway?

Escenarios ideales:

• Proyectos con evolución frecuente del esquema.
• Equipos distribuidos o con múltiples entornos (dev, test, prod).
• Necesidad de auditoría o trazabilidad de cambios en el esquema.

Ventajas sobre auto-DDL de JPA (spring.jpa.hibernate.ddl-auto):

• Evita sobrescritura accidental de datos.
• Versionado explícito de cambios.
• Mayor control y trazabilidad de la evolución del esquema.

Implementación en Spring Boot

Requisitos previos:

Agrega las siguientes dependencias en tu archivo pom.xml:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
    </dependency>
</dependencies>

Para Gradle: implementation 'org.flywaydb:flyway-core'

Configuración básica (application.properties):

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.username=sa
spring.datasource.password=
spring.datasource.driver-class-name=org.h2.Driver

spring.jpa.hibernate.ddl-auto=none

spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migration

Ejemplo Práctico: Proyecto de Gestión de Usuarios

Supongamos una aplicación con una tabla users. Vamos a construir el esquema paso a paso usando Flyway.

Estructura del proyecto:

src/
 └── main/
     └── resources/
         └── db/
             └── migration/
                 ├── V1__Create_user_table.sql
                 └── V2__Add_user_role_column.sql

Primera Iteración – Crear tabla users

Archivo: V1__Create_user_table.sql

CREATE TABLE users (
    id BIGINT PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) UNIQUE
);

✅ Al iniciar la aplicación, Flyway detecta este archivo y lo ejecuta. Marca la versión como aplicada en su propia tabla de control (flyway_schema_history).

Segunda Iteración – Agregar columna role

Archivo: V2__Add_user_role_column.sql

ALTER TABLE users ADD COLUMN role VARCHAR(20) DEFAULT 'USER';

✅ Flyway identifica que esta versión aún no ha sido aplicada, la ejecuta y actualiza su historial. No vuelve a aplicar la versión 1.

Visualización del Estado de la Base de Datos Tras las Migraciones

Después de ejecutar las dos migraciones (V1 y V2), Flyway deja una huella en la base de datos que te permite auditar el estado de los cambios.

Tablas creadas tras las migraciones:

1. Tabla de usuarios (users):

SELECT * FROM users;

Estructura:

Columna	Tipo	Restricciones
id	BIGINT	PRIMARY KEY
username	VARCHAR(50)	NOT NULL
email	VARCHAR(100)	UNIQUE
role	VARCHAR(20)	DEFAULT ‘USER’

2. Tabla de control de Flyway (flyway_schema_history):

SELECT * FROM flyway_schema_history;

Ejemplo de contenido:

installed_rank	version	description	type	script	success
1	1	Create user table	SQL	V1__Create_user_table.sql	true
2	2	Add user role column	SQL	V2__Add_user_role_column.sql	true

Migraciones Java-based

Aunque Flyway trabaja perfectamente con scripts SQL, en algunos casos puede ser útil definir migraciones programáticamente en Java. Esto es útil cuando:

• Necesitas lógica condicional o control de flujo.
• Quieres reutilizar servicios de Spring.
• Trabajas con bases de datos no relacionales o lógicas avanzadas.

Cómo crear una migración Java:

1. Implementa la clase extendiendo BaseJavaMigration.
2. Ubícala en el paquete db.migration o configura la ubicación.
3. Nómbrala con el patrón V{n}__Descripción.

Ejemplo: Crear tabla de auditoría

package db.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;

import java.sql.Statement;

public class V3__Create_audit_table extends BaseJavaMigration {
    @Override
    public void migrate(Context context) throws Exception {
        try (Statement stmt = context.getConnection().createStatement()) {
            stmt.execute("""
                CREATE TABLE audit (
                    id BIGINT PRIMARY KEY AUTO_INCREMENT,
                    action VARCHAR(100),
                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
                );
            """);
        }
    }
}

Configuración adicional si se cambia la ubicación:

spring.flyway.locations=classpath:db/migration
spring.flyway.java-migrations-location=com.ejemplo.migraciones

Tabla Resumen

Concepto	Descripción
Migraciones	Archivos SQL con prefijo V{n}__ que modifican el esquema.
Integración con Spring	Ejecuta automáticamente migraciones al iniciar la app.
Ubicación por defecto	classpath:db/migration
Uso recomendado	Proyectos con cambios frecuentes en el esquema y colaboración en equipo.

Conclusión

Flyway no solo gestiona migraciones de manera declarativa (con SQL), sino que también ofrece una vía programática potente para casos avanzados. Su integración con Spring Boot hace que los cambios de esquema sean seguros, trazables y consistentes.

Recomendaciones Finales:

• Nunca modifiques un script ya aplicado.
• Usa migraciones Java cuando lo SQL no sea suficiente.
• Verifica la tabla flyway_schema_history para diagnosticar errores o validar versiones.

Referencias

• Flyway - Documentación oficial
• Spring Boot - Flyway Integration