Cómo integrar Flyway en un proyecto Spring con Kotlin y Gradle

Fecha de publicación: 2025-04-04

Flyway es una herramienta poderosa para versionar y automatizar migraciones de base de datos. En este tutorial veremos cómo configurarlo desde cero en un proyecto con Spring Boot, Kotlin y Gradle Kotlin DSL (build.gradle.kts). También exploraremos cómo gestiona la integridad de las migraciones y por qué es una excelente opción para equipos backend.

En muchos proyectos, especialmente en etapas iniciales, es común modificar el esquema directamente desde herramientas gráficas o scripts sueltos sin control de versiones. Esto lleva rápidamente a problemas como:

Desincronización entre entornos (lo que funciona en local falla en staging o producción)
Dificultad para reproducir errores en ambientes similares
Falta de trazabilidad sobre cuándo y por qué se hizo un cambio
Riesgo de sobrescribir o perder datos en despliegues

Adoptar una herramienta como Flyway desde el principio evita estos dolores de cabeza y aporta control, orden y seguridad.

🚀 Paso 1: Agrega Flyway a tu build.gradle.kts

dependencies {
    implementation("org.flywaydb:flyway-core")
    runtimeOnly("org.postgresql:postgresql") // o el driver que uses
}

Asegúrate también de tener el plugin de Spring Boot y el plugin de Kotlin configurados correctamente en la sección plugins.

📁 Paso 2: Crea la carpeta de migraciones

Por defecto, Flyway busca los scripts en src/main/resources/db/migration. Ahí debes crear archivos como:

-- V1__init_schema.sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL
);

Cada script debe seguir el patrón V<versión>__<descripción>.sql. Cuando tu app se levanta, Flyway detecta si hay nuevas migraciones por aplicar.

➕ Paso 3: Agrega una segunda migración

Supongamos que ahora quieres agregar una tabla de pedidos:

-- V2__create_orders_table.sql
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    user_id INT REFERENCES users(id),
    total DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMP DEFAULT now()
);

Cuando esta migración esté en la carpeta, Flyway la detectará automáticamente y la aplicará si aún no ha sido ejecutada.

⚙️ Paso 4: Configura la conexión a la base de datos

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: myuser
    password: secret
  flyway:
    enabled: true

Esto indica que Flyway está habilitado y usará las credenciales proporcionadas para conectarse y aplicar las migraciones.

📋 ¿Qué es la tabla flyway_schema_history?

Una vez que Flyway se ejecuta por primera vez, crea automáticamente una tabla llamada flyway_schema_history. Esta tabla registra:

El número de versión de cada migración (por ejemplo, V1, V2, etc.)
El nombre del script
El estado (ejecutado, fallido, pendiente)
La fecha y hora en que se aplicó

SELECT * FROM flyway_schema_history;

Esta tabla actúa como un registro de auditoría y permite que Flyway sepa qué scripts ya han sido aplicados, evitando así reejecutarlos.

✅ Ventajas clave de usar Flyway

Control de versiones de tu esquema de base de datos
Facilidad para mantener entornos consistentes (dev, staging, prod)
Auditoría y trazabilidad de cambios
Facilidad de rollback manual si algo falla
Soporte para múltiples entornos y pipelines CI/CD
Integración natural con Spring Boot
Facilidad para onboarding de nuevos desarrolladores con un esquema listo para ejecutar

🧪 Paso 5: Corre la aplicación y verifica

Al iniciar tu app, deberías ver logs similares a:

Successfully validated 2 migrations (execution time 00:00.032s)
Current version of schema "public": 2

Esto confirma que ambas migraciones han sido aplicadas y tu base de datos está en la versión correcta.

📌 Conclusión

Flyway es una solución robusta y sencilla para gestionar el ciclo de vida de tu base de datos. Al integrarlo con Spring Boot, Kotlin y Gradle, aseguras consistencia, control y trazabilidad en tus migraciones.

Con Flyway, cada cambio queda documentado y automatizado. Ideal para equipos que buscan calidad, mantenibilidad y confianza desde el primer commit.