Migraciones de base de datos versionadas con Flyway en Spring Boot

Si alguna vez has tenido que preguntar "¿este script ya lo ejecutaste en producción?" sabes exactamente el problema que resuelve Flyway. Gestionar cambios de esquema a mano es una fuente constante de errores: scripts que se ejecutan dos veces, columnas que existen en local pero no en staging, migraciones aplicadas en distinto orden según quién hizo el despliegue. Flyway acaba con todo eso.

El problema de los cambios de esquema manuales

En un proyecto con varios desarrolladores, la base de datos cambia continuamente. Alguien añade una columna, otro crea un índice, un tercero renombra una tabla. Sin coordinación, los entornos acaban desfasados. El típico archivo schema.sql compartido en un canal de Slack no escala. Tampoco los comentarios del tipo "ejecuta esto en prod antes del despliegue del viernes".

Los problemas más frecuentes son dos: ejecutar un script más de una vez (lo que puede corromper datos o lanzar errores de duplicado) y no saber con exactitud qué versión del esquema tiene cada entorno. Flyway resuelve los dos con un mecanismo sencillo: aplica los scripts en orden y guarda en una tabla qué ya se ha ejecutado.

Qué es Flyway y cómo funciona

Flyway es una herramienta de migración de base de datos. Lee scripts SQL de una carpeta predefinida, los ordena por versión y los aplica uno a uno sobre la base de datos. Después de ejecutar cada script, guarda un registro en la tabla flyway_schema_history con el número de versión, el nombre del script, su checksum y si se ejecutó con éxito. La próxima vez que Flyway arranca, compara esa tabla con los scripts disponibles y solo ejecuta los nuevos.

Cualquier script ya aplicado es intocable. Si alguien modifica un archivo de migración que Flyway ya ejecutó, la herramienta detecta que el checksum no coincide y falla el arranque. Eso protege el historial de cambios.

Convención de nombres de los scripts

Flyway distingue tres tipos de migraciones según el prefijo del nombre del archivo:

• Versionadas: V1__create_users.sql, V2__add_email_index.sql. Se ejecutan una sola vez, en orden. El número de versión puede ser 1, 1.1, 2024.06.01, etc.
• Repetibles: R__refresh_view.sql. Se ejecutan cada vez que cambia su contenido. Útiles para recrear vistas, procedimientos almacenados o datos de referencia.
• Undo (solo en Flyway Teams): U1__undo_create_users.sql. Permiten revertir la migración correspondiente de forma automática.

El doble guion bajo separa el prefijo y la versión del nombre descriptivo. El nombre descriptivo no afecta a la ejecución pero sí aparece en el historial y en los logs, así que merece la pena escribirlo bien: V3__add_created_at_to_orders.sql dice mucho más que V3__update.sql.

Integración con Spring Boot

Spring Boot detecta Flyway automáticamente si está en el classpath. Solo necesitas añadir la dependencia en pom.xml:

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>

Por defecto, Spring Boot busca los scripts en src/main/resources/db/migration/. Puedes cambiar eso y ajustar otros parámetros en application.yml:

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    baseline-version: 0
    validate-on-migrate: true

Cuando arranca la aplicación, antes de que Spring levante el contexto completo, Flyway comprueba el estado del esquema y aplica las migraciones pendientes. Si alguna falla, el arranque se cancela. No llega ninguna petición a una base de datos en estado inconsistente.

La tabla flyway_schema_history

Esta tabla es el corazón de Flyway. Se crea automáticamente la primera vez que se ejecuta y contiene una fila por cada migración aplicada:

installed_rank | version | description          | type | script                        | checksum   | installed_by | success
1              | 1       | create users         | SQL  | V1__create_users.sql          | 1234567890 | postgres     | true
2              | 2       | add email index      | SQL  | V2__add_email_index.sql       | 0987654321 | postgres     | true
3              | 3       | add created at orders| SQL  | V3__add_created_at_to_orders  | 1122334455 | postgres     | true

No toques esta tabla a mano. Si necesitas corregir algo, usa los comandos de Flyway.

Comandos de Flyway que debes conocer

Flyway ofrece varios comandos que puedes ejecutar desde la CLI, desde Maven/Gradle o mediante el API de Java:

• info: muestra el estado de todas las migraciones, cuáles están pendientes y cuáles ya se aplicaron. El primero que ejecutarás cuando no sepas en qué punto está un entorno.
• validate: comprueba que los scripts del proyecto coinciden con lo que hay en flyway_schema_history. Falla si alguien modificó un script ya aplicado.
• baseline: marca el estado actual del esquema como versión base. Útil cuando introduces Flyway en un proyecto existente con una base de datos ya creada.
• repair: corrige entradas fallidas en flyway_schema_history o actualiza checksums de migraciones que se editaron (con cuidado, solo en desarrollo).
• clean: borra todos los objetos del esquema. Destructivo. Solo para entornos de desarrollo o pruebas, nunca en producción. Con Spring Boot puedes desactivarlo con spring.flyway.clean-disabled=true.

Flyway en CI/CD

Uno de los puntos fuertes de Flyway es lo bien que encaja en un pipeline de integración continua. El flujo habitual es:

1. El pipeline levanta la base de datos (o conecta a un entorno de staging).
2. Ejecuta flyway validate para asegurarse de que no hay scripts modificados.
3. Ejecuta flyway migrate para aplicar los cambios pendientes.
4. Si alguno de los dos pasos falla, el pipeline se detiene y no se despliega la aplicación.

Este orden garantiza que nunca llegas a producción con un esquema desincronizado respecto al código. Para proyectos que usan despliegues blue-green o canary, conviene que las migraciones sean compatibles con la versión anterior del código (añadir columnas con valor por defecto antes de que el código las use, borrar columnas después de que el código haya dejado de referenciarlas).

Flyway vs Liquibase: cuándo elegir cada uno

La pregunta aparece en cualquier proyecto Java que empieza a gestionar migraciones. La diferencia principal está en el formato de los changesets:

• Flyway trabaja con SQL puro. Lo que escribes es exactamente lo que se ejecuta. Sencillo de depurar, fácil de revisar en pull requests, sin abstracciones.
• Liquibase usa XML, YAML, JSON o SQL. Ofrece más funciones: rollback automático en la edición gratuita, soporte multi-base-de-datos sin reescribir scripts, y herramientas visuales de gestión.

Flyway es la opción más cómoda si tu equipo ya conoce SQL y no necesita cambiar de motor de base de datos con frecuencia. Liquibase gana cuando necesitas portabilidad real entre motores (PostgreSQL, MySQL, Oracle) o rollback automático sin pagar licencia Teams.

Para la mayoría de proyectos Spring Boot con PostgreSQL o MySQL, Flyway es suficiente y más sencillo de mantener. Si la organización ya usa Liquibase o tiene requisitos de auditoría complejos, puede merecer la pena el cambio. Igual que elegir patrones de diseño en Java para estructurar la capa de persistencia, la decisión depende del contexto del proyecto.

Buenas prácticas con Flyway

Algunas reglas que te ahorran problemas:

• No modifiques una migración ya aplicada. Si te equivocaste en V3__create_orders.sql y ya está en producción, crea V4__fix_orders.sql que corrija el error. Flyway detectará el checksum modificado y fallará.
• Los rollbacks son nuevas migraciones. Si necesitas deshacer un cambio, escribe una nueva migración que lo revierta. Eso mantiene el historial completo y auditadle.
• Prueba en staging primero. Antes de aplicar una migración en producción, ejecútala en un entorno con datos reales o un volcado reciente. Las migraciones que funcionan en local a veces tardan minutos en tablas de cientos de millones de filas.
• Usa validate-on-migrate: true para que Flyway compruebe la coherencia antes de aplicar cualquier cambio.
• Desactiva clean en producción con spring.flyway.clean-disabled=true. Un flyway clean accidental en producción borra el esquema entero.

Flyway Teams vs Community

La edición gratuita (Community) cubre la mayoría de casos de uso: migraciones versionadas, repetibles, validación, baseline y repair. Las funciones de pago (Teams y Enterprise) incluyen:

• Dry-run: genera un script SQL con todas las migraciones pendientes sin ejecutarlas. Permite revisión manual antes de aplicar cambios.
• Undo automático: ejecuta el script U correspondiente si una migración falla.
• Verificación de objetos del esquema fuera de Flyway.
• Integración con herramientas de auditoría empresarial.

Para la mayoría de equipos, Community es más que suficiente. Teams tiene sentido en entornos regulados donde necesitas dry-run antes de cada despliegue o rollback automático garantizado.

Si estás construyendo sobre Java 25 LTS, la plataforma de referencia actual, Flyway funciona sin cambios: la integración con Spring Boot es transparente independientemente de la versión de Java.

La documentación oficial está en documentation.red-gate.com/fd/ y cubre todos los parámetros de configuración, comandos y casos de uso avanzados.

Imagen: Pexels / panumas nikhomkhai