Migraciones de Base de Datos
ATC-API gestiona el esquema de la base de datos exclusivamente a través de Flyway, integrado con Spring Boot. Ningún cambio estructural debe hacerse directamente desde el gestor de base de datos.
Si se crean o modifican columnas directamente desde la base de datos sin su migración correspondiente, el proyecto no arrancará. Hibernate valida que el esquema de la BD coincida exactamente con el de las entidades al iniciar.
¿Cómo funciona la validación?
Spring Hibernate con ddl-auto: validate compara el esquema real de la BD contra las entidades al levantar el proyecto. Cualquier diferencia lanza un error fatal en el arranque.
Para más detalle sobre esta validación: vladmihalcea.com — Validate DDL Schema with Spring Hibernate
Estructura de Carpetas
Las migraciones viven dentro de la carpeta migration/. Cada funcionalidad tiene su propia subcarpeta:
- V1724000000__init_schema.sql
- V1724000001__add_new_table.sql
- R__people_view.sql
Si ya existe una carpeta para la feature en la que trabajas, úsala. Si no existe, créala con el nombre de la funcionalidad.
Tipos de Archivos
Flyway maneja dos tipos de archivos de migración con comportamientos distintos:
| Prefijo | Nombre | Comportamiento |
|---|---|---|
V | Versionado | Se ejecuta en orden según su versión. Una vez aplicado, no se puede modificar. |
R | Repetible | Se ejecuta al final, después de todos los V. Se re-ejecuta si su contenido cambia. |
Los archivos V son inmutables una vez aplicados. Flyway guarda un checksum de cada uno y falla si detecta que fue modificado. Si necesitas un cambio, crea una nueva migración.
Nomenclatura y Estructura de Archivos
<Prefijo><Versión>__<Descripción>.sql- El separador entre versión y descripción son dos guiones bajos
__. - La descripción usa guiones bajos en lugar de espacios.
- La versión es un timestamp Unix (Epoch) para evitar conflictos entre el equipo.
Ejemplos
-- Versionados (se ejecutan en orden)
V1724000000__init_schema.sql
V1724000001__add_new_table.sql
V1724000002__add_indexes_to_new_table.sql
-- Repetibles (se ejecutan al final)
R__people_view.sqlEl primer archivo de cada feature
El primer query que define las tablas base de una funcionalidad debe usar la palabra Schema en su nombre:
V1724000000__Schema_nombre_funcionalidad.sqlGenerar el Número de Versión (Epoch)
Para que todo el equipo pueda crear archivos sin que los números de versión colisionen, usamos el timestamp Unix (Epoch) como versión.
Herramienta: epochconverter.com
Abrir Epoch Converter
Ve a epochconverter.com y copia el timestamp actual (el número que aparece en la parte superior).
Usar el timestamp como versión
-- Ejemplo con timestamp generado en el momento de crear el archivo
V1743500000__add_user_table.sqlNombrar y colocar el archivo
Coloca el archivo dentro de la carpeta de tu feature en migration/.