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 equivalentes
- Falta de trazabilidad sobre cuándo y por qué se realizó un cambio
- Riesgo de sobrescribir o perder datos en los despliegues
🚀 Paso 1: Agrega Flyway a tu build.gradle.kts
kotlin
1dependencies {
2 implementation("org.flywaydb:flyway-core")
3 runtimeOnly("org.postgresql:postgresql") // o el driver que uses
4}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:sql
1-- V1__init_schema.sql
2CREATE TABLE users (
3 id SERIAL PRIMARY KEY,
4 name VARCHAR(100) NOT NULL,
5 email VARCHAR(100) UNIQUE NOT NULL
6);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:
sql
1-- V2__create_orders_table.sql
2CREATE TABLE orders (
3 id SERIAL PRIMARY KEY,
4 user_id INT REFERENCES users(id),
5 total DECIMAL(10,2) NOT NULL,
6 created_at TIMESTAMP DEFAULT now()
7);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
yaml
1spring:
2 datasource:
3 url: jdbc:postgresql://localhost:5432/mydb
4 username: myuser
5 password: secret
6 flyway:
7 enabled: trueEsto 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ó
sql
1SELECT * 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í ejecutarlos de nuevo.
✅ 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
- Facilita el 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:
text
1Successfully validated 2 migrations (execution time 00:00.032s)
2Current version of schema "public": 2Esto 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.
