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

El Versionado Semántico (SemVer) es una herramienta fundamental para comunicar de forma precisa los cambios en el software, facilitando el mantenimiento y la colaboración. Complementarlo con un CHANGELOG bien estructurado potencia la transparencia y la trazabilidad, ofreciendo una visión detallada de la evolución de cada versión. En este artículo, exploraremos en profundidad cómo adoptar SemVer y cómo mantener un CHANGELOG que vaya de la mano para optimizar tu proceso de desarrollo.

---

Introducción

El control de versiones en el desarrollo de software se convierte en una ventaja competitiva cuando se implementa de forma clara y estructurada. SemVer aporta un sistema numérico que indica el alcance de los cambios (cambios mayores, menores o correcciones), mientras que el CHANGELOG documenta y narra el proceso evolutivo de tu proyecto. Esta sinergia no solo facilita la colaboración interna, sino que también mejora la comunicación con los usuarios y clientes, ayudando a identificar qué, cuándo y por qué se han realizado determinados cambios.

---

1. Estructura Básica de SemVer

El formato principal de SemVer se compone de tres segmentos:

MAJOR.MINOR.PATCH

• MAJOR: Se incrementa cuando se realizan cambios incompatibles con versiones anteriores (por ejemplo, la eliminación o modificación de una API pública).
• MINOR: Se aumenta cuando se agregan nuevas funcionalidades de manera compatible.
• PATCH: Se incrementa al corregir errores sin afectar las funcionalidades existentes.

Etiquetas Adicionales

• Pre-release: Indica versiones inestables, por ejemplo, 1.0.0-beta.1.
• Build Metadata: Añade información adicional de compilación, como en 1.0.0+20230901.

---

2. Reglas para Incrementar Versiones

Al actualizar una versión, es fundamental distinguir entre los diferentes tipos de cambios:

• Versión MAJOR (X.y.z → X+1.0.0):
  Se utiliza cuando se introducen cambios que rompen la compatibilidad con versiones anteriores.
  Ejemplo: Modificar o eliminar una API de forma incompatible.

• Versión MINOR (x.Y.z → x.Y+1.0):
  Se incrementa al introducir nuevas funcionalidades sin afectar la compatibilidad.
  Ejemplo: Agregar un método opcional a una clase.

• Versión PATCH (x.y.Z → x.y.Z+1):
  Se utiliza para corregir errores, preservando la compatibilidad con versiones anteriores.
  Ejemplo: Arreglar un error en una función de cálculo.

---

3. Ejemplos Prácticos

• Versión Inicial: 0.1.0
  Indica la fase de desarrollo inicial donde el software puede sufrir cambios drásticos.

• Primera Versión Estable: 1.0.0
  Marca el lanzamiento oficial cuando la API es considerada estable y está documentada.

• Actualización con Nueva Funcionalidad:
  De 1.0.0 a 1.1.0 para incorporar mejoras sin romper compatibilidad.

• Corrección Crítica:
  De 1.1.0 a 1.1.1 para solucionar errores puntuales.

• Cambio Incompatible:
  De 1.1.1 a 2.0.0 cuando se realizan modificaciones que requieren cambios en el código del consumidor.

---

4. La Importancia de Mantener un CHANGELOG

Un CHANGELOG es un registro sistemático y estructurado que documenta de manera cronológica cada cambio, mejora y corrección en el software. Su incorporación al proceso de SemVer proporciona un contexto narrativo, detallando el "porqué" y el "cómo" detrás de cada versión.

Beneficios Clave del CHANGELOG

• Claridad en la Comunicación:
  Complementa los números de versión de SemVer con descripciones detalladas de los cambios implementados.

• Trazabilidad y Historial:
  Permite rastrear la evolución del software a lo largo del tiempo, facilitando la depuración y la revisión histórica.

• Transparencia Interna y Externa:
  Informa tanto a los desarrolladores como a los usuarios finales sobre las mejoras y cambios realizados, fortaleciendo la confianza en el proceso de actualización.

• Soporte a la Automatización:
  Herramientas integradas pueden actualizar el CHANGELOG de forma automática al seguir convenciones de commits, como Conventional Commits.

Mejores Prácticas para un CHANGELOG Efectivo

1. Estructuración Clara:
   Organiza el CHANGELOG por versiones, empezando por la más reciente. Dentro de cada versión, clasifica los cambios en secciones como "Añadido", "Modificado", "Corregido" y "Notas de Deprecación".

2. Actualización Continua:
   Registra los cambios a medida que se van implementando para capturar detalles precisos y evitar omisiones.

3. Integración con el Proceso de Versionado:
   Vincula cada entrada del CHANGELOG con commits específicos y números de versión, facilitando la sincronización entre lo que se comunica y lo que se versiona.

4. Comunicación Externa:
   Publica el CHANGELOG en el repositorio del proyecto y en las notas de lanzamiento para que usuarios y colaboradores comprendan la evolución del software.

Ejemplo Básico de CHANGELOG

# CHANGELOG

## [2.0.0] - 2025-04-01
### Añadido
- Nueva función para exportación de datos.
### Modificado
- Actualización del sistema de autenticación (rompe compatibilidad con versiones anteriores).
### Corregido
- Error en el módulo de notificaciones.

## [1.2.1] - 2025-03-15
### Corregido
- Solucionado el error en la actualización automática del perfil del usuario.

---

5. Herramientas para Generar CHANGELOG Automáticamente

Usar herramientas automatizadas facilita enormemente el mantenimiento de un CHANGELOG claro y actualizado. A continuación, se presentan algunas opciones destacadas:

Conventional Changelog

• Base de muchas herramientas automatizadas.
• Genera el CHANGELOG.md a partir de commits con formato estándar.
• Ejemplo:

npx conventional-changelog -p angular -i CHANGELOG.md -s

standard-version

• Automatiza el versionado y el changelog sin publicar a npm.
• Ideal para control manual con automatización parcial.

npm install --save-dev standard-version
npx standard-version

semantic-release

• Automatiza TODO: changelog, versionado, publicación en npm o GitHub.
• Requiere entorno CI/CD (ej: GitHub Actions).

npm install --save-dev semantic-release

release-it

• Personalizable, ideal para flujos mixtos.

npm install --save-dev release-it
npx release-it

---

6. Convenciones de Commit (Conventional Commits)

Estas convenciones estructuran los mensajes de commit para que puedan ser procesados automáticamente:

<tipo>(opcional: alcance): descripción

[opcional] cuerpo del mensaje
[opcional] notas de ruptura (BREAKING CHANGE)

Ejemplos:

feat(auth): agregar login con Google
fix(api): corregir error de serialización
docs(readme): actualizar instrucciones de uso
BREAKING CHANGE: se eliminó el endpoint /v1/user

Tipos más comunes:

Tipo	Uso
feat	Nueva funcionalidad
fix	Corrección de errores
docs	Cambios en la documentación
style	Cambios de formato (espacios, comas, etc.)
refactor	Refactorización del código sin cambios de funcionalidad
test	Cambios relacionados a pruebas
chore	Tareas menores de mantenimiento

---

7. Gestión de Dependencias

El versionado semántico también afecta cómo se definen y gestionan las dependencias en los proyectos:

• Caret ( ^ ):
  Permite actualizaciones de versiones MINOR y PATCH. Por ejemplo, ^1.2.3 abarca versiones de la serie 1.x.x.

• Tilde ( ~ ):
  Restringe las actualizaciones a parches solamente. Por ejemplo, ~1.2.3 asegura que se mantenga la versión 1.2.x.

---

8. Herramientas Recomendadas

• semver: Librería para comparar y validar versiones.
• Conventional Commits: Estándar de mensajes para facilitar changelogs automáticos.
• GitHub Actions/GitLab CI: Automatiza versiones y publicaciones.
• semantic-release / standard-version / release-it: Para generar changelogs y manejar versiones automáticamente.

---

Tabla Resumen

Aspecto	Descripción	Ejemplo
Formato Básico de SemVer	MAJOR.MINOR.PATCH	2.4.1
Versión MAJOR	Cambios incompatibles que rompen versiones anteriores	1.1.1 → 2.0.0
Versión MINOR	Nuevas funcionalidades sin romper compatibilidad	1.0.0 → 1.1.0
Versión PATCH	Correcciones de errores sin afectar la funcionalidad	1.1.0 → 1.1.1
Pre-release	Versión inestable para pruebas	1.0.0-beta.1
Build Metadata	Información adicional de compilación	1.0.0+20230901
Gestión de Dependencias	Uso de caret (^) para permitir MINOR y PATCH; tilde (~) para solo PATCH	^1.2.3 y ~1.2.3
CHANGELOG	Registro detallado de cambios, organizado por versiones y secciones claras	Ver ejemplo en el artículo
Convenciones de Commit	Estilo estructurado que facilita la generación automática de changelog	feat, fix, chore, etc.
Herramientas de Automatización	Facilitan la gestión de versiones y changelog	semantic-release, standard-version, release-it

---

Conclusión

Integrar el Versionado Semántico con un CHANGELOG completo y bien documentado garantiza un proceso de actualización y mantenimiento de software más transparente y predecible. Adoptar ambas prácticas no solo mejora la organización interna y el flujo de trabajo, sino que también fortalece la comunicación con los usuarios al explicar de forma detallada cada cambio realizado. Utiliza esta guía para transformar tu estrategia de versionado y construir una base sólida para el crecimiento y la evolución de tu proyecto de software.