Flyway + Spring Boot
Tutorial completo de database migrations
Backend Development Guide
1 Conceptos clave
Flyway es una herramienta de database migration que versiona y aplica cambios en el esquema de
base de datos de forma ordenada, repetible y auditable. Se integra nativamente con Spring Boot.
Al arrancar la aplicación, Flyway:
• Lee la tabla flyway_schema_history para saber qué migraciones ya fueron aplicadas.
• Detecta los archivos SQL nuevos en db/migration/ comparando por versión y checksum.
• Aplica las pendientes en orden: V1 → V2 → Vn.
• Si un archivo ya aplicado fue modificado, falla el arranque (protección de integridad).
Nota: El checksum de cada archivo SQL se guarda en flyway_schema_history. Nunca modifiques un
archivo ya aplicado.
Tipo Prefijo Ejemplo
Versionada V{n}__{desc}.sql V1__init_schema.sql
Repetible R__{desc}.sql R__create_views.sql
Undo (Teams) U{n}__{desc}.sql U1__undo_init.sql
2 Setup inicial
Dependencia Maven
<dependency>
<groupId>[Link]</groupId>
<artifactId>flyway-core</artifactId>
<!-- versión manejada por Spring Boot BOM -->
</dependency>
<!-- MySQL/MariaDB -->
<dependency>
<groupId>[Link]</groupId>
<artifactId>flyway-mysql</artifactId>
</dependency>
<!-- SQL Server -->
<dependency>
<groupId>[Link]</groupId>
<artifactId>flyway-sqlserver</artifactId>
</dependency>
Nota: PostgreSQL y H2 están soportados por flyway-core sin dependencia extra.
Configuración en [Link]
[Link]=jdbc:postgresql://localhost:5432/midb
[Link]=postgres
[Link]=secret
[Link]=true
[Link]=classpath:db/migration
[Link]-on-migrate=false
# Hibernate valida el schema pero no lo modifica
[Link]-auto=validate
Nota: ddl-auto=validate es la combinación ideal con Flyway: Hibernate valida que las entidades coincidan
con el esquema real, pero no lo modifica.
3 Estructura de archivos
src/
■■■ main/
■■■ resources/
■■■ db/
■■■ migration/
■■■ V1__create_usuarios.sql
■■■ V2__add_email_unique.sql
■■■ V3__create_tabla_roles.sql
■■■ R__vista_usuarios_activos.sql ← repetible
4 Primeras migraciones — ejemplos reales
V1__create_usuarios.sql
CREATE TABLE usuarios (
id BIGSERIAL PRIMARY KEY,
username VARCHAR(50) NOT NULL UNIQUE,
email VARCHAR(100) NOT NULL UNIQUE,
activo BOOLEAN NOT NULL DEFAULT TRUE,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
V2__create_roles.sql
CREATE TABLE roles (
id SERIAL PRIMARY KEY,
nombre VARCHAR(30) NOT NULL UNIQUE
);
CREATE TABLE usuario_roles (
usuario_id BIGINT NOT NULL REFERENCES usuarios(id),
rol_id INTEGER NOT NULL REFERENCES roles(id),
PRIMARY KEY (usuario_id, rol_id)
);
V3__add_telefono_usuarios.sql
ALTER TABLE usuarios
ADD COLUMN telefono VARCHAR(20);
R__seed_roles.sql — migración repetible
Las repetibles se ejecutan cada vez que su contenido cambia. Sirven para views, functions y datos de
referencia.
INSERT INTO roles (nombre) VALUES ('ADMIN')
ON CONFLICT (nombre) DO NOTHING;
INSERT INTO roles (nombre) VALUES ('USER')
ON CONFLICT (nombre) DO NOTHING;
INSERT INTO roles (nombre) VALUES ('AUDITOR')
ON CONFLICT (nombre) DO NOTHING;
5 La tabla flyway_schema_history
Flyway crea y gestiona esta tabla automáticamente para llevar el control de todas las migraciones
aplicadas.
SELECT installed_rank, version, description, type, script, checksum, success
FROM flyway_schema_history
ORDER BY installed_rank;
-- Resultado:
-- rank | version | description | script | success
-- -----+---------+----------------------+---------------------------+---------
-- 1 | 1 | create usuarios | V1__create_usuarios.sql | true
-- 2 | 2 | create roles | V2__create_roles.sql | true
-- 3 | 3 | add telefono | V3__add_telefono.sql | true
Nota: Nunca modifiques un archivo SQL ya aplicado. Flyway detectará el cambio de checksum y fallará el
arranque.
6 Configuración avanzada — [Link]
spring:
flyway:
enabled: true
locations:
- classpath:db/migration
- classpath:db/seed
baseline-on-migrate: false
baseline-version: 0
out-of-order: false
validate-on-migrate: true
clean-disabled: true # IMPORTANTE: evita borrado accidental en prod
table: flyway_schema_history
schemas:
- public
placeholders:
schema: public
environment: ${[Link]}
Usar placeholders en los SQL
CREATE TABLE ${schema}.auditoria (
id BIGSERIAL PRIMARY KEY,
tabla VARCHAR(50),
operacion VARCHAR(10),
fecha TIMESTAMP DEFAULT NOW()
);
7 Múltiples ambientes
resources/
■■■ db/
■■■ migration/ ← siempre se aplica
■ ■■■ V1__schema.sql
■ ■■■ V2__alter.sql
■■■ testdata/ ← solo en dev/test
■■■ V100__seed_test_data.sql
# [Link]
spring:
flyway:
locations:
- classpath:db/migration
- classpath:db/testdata
# [Link]
spring:
flyway:
locations:
- classpath:db/migration
8 Migraciones Java
Cuando el SQL no alcanza — por ejemplo para migrar datos con lógica de negocio — podés escribir la
migración en Java:
package [Link];
import [Link];
import [Link];
import [Link];
import [Link];
// El nombre de clase sigue la misma convención: V4__Descripcion
public class V4__Migrar_passwords_a_bcrypt extends BaseJavaMigration {
@Override
public void migrate(Context context) throws Exception {
JdbcTemplate jdbc = new JdbcTemplate(
new SingleConnectionDataSource([Link](), true)
);
List<Map<String, Object>> usuarios = [Link](
"SELECT id, password_plain FROM usuarios WHERE password_hash IS NULL"
);
for (Map<String, Object> u : usuarios) {
String hash = [Link](
(String) [Link]("password_plain"), [Link]()
);
[Link](
"UPDATE usuarios SET password_hash = ? WHERE id = ?",
hash, [Link]("id")
);
}
[Link]("ALTER TABLE usuarios DROP COLUMN IF EXISTS password_plain");
}
}
Nota: Las migraciones Java deben estar en el paquete [Link] para que Flyway las detecte
automáticamente.
9 Comandos Maven útiles
Comando Descripción
./mvnw flyway:migrate Aplica todas las migraciones pendientes
./mvnw flyway:info Muestra el estado de cada migración
./mvnw flyway:validate Valida checksums (útil en CI/CD)
./mvnw flyway:repair Repara tabla de historial / migración fallida
./mvnw flyway:clean ■ Borra todo — deshabilitado en prod
10 Integración con tests
Test con H2 (en memoria)
# [Link]
spring:
datasource:
url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;MODE=PostgreSQL
driver-class-name: [Link]
flyway:
enabled: true
locations: classpath:db/migration
jpa:
hibernate:
ddl-auto: validate
Test con Testcontainers (PostgreSQL real)
@SpringBootTest
@Testcontainers
class MigracionIntegrationTest {
@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
.withDatabaseName("testdb")
.withUsername("test")
.withPassword("test");
@DynamicPropertySource
static void setProps(DynamicPropertyRegistry registry) {
[Link]("[Link]", postgres::getJdbcUrl);
[Link]("[Link]", postgres::getUsername);
[Link]("[Link]", postgres::getPassword);
}
@Autowired
Flyway flyway;
@Test
void todas_las_migraciones_deben_ser_validas() {
MigrationInfoService info = [Link]();
long fallidas = [Link]([Link]())
.filter(m -> [Link]().isFailed())
.count();
assertThat(fallidas).isZero();
}
}
11 DB existente sin historial — baseline-on-migrate
Si tenés una base de datos en producción con un esquema existente pero que nunca usó Flyway:
[Link]-on-migrate=true
[Link]-version=1
Nota: Esto le dice a Flyway: "la DB ya está en versión 1, no ejecutes V1, solo las posteriores". Usalo una
sola vez y después volvé a false.
12 Buenas prácticas
• Nunca modificar un archivo .sql ya commiteado y aplicado. Creá una nueva versión.
• Un cambio por archivo: facilita el rollback manual y el entendimiento del historial.
• Nombrar descriptivamente: V5__add_index_usuarios_email.sql es mejor que V5__fix.sql.
• clean-disabled: true en producción: evita accidentes catastróficos.
• Incluir migraciones en el mismo PR que los cambios de código que las requieren.
• Validar en CI con flyway:validate antes de hacer deploy.
• Para rollback: escribir scripts V{n}__rollback_*.sql manuales. Los Undo scripts requieren Flyway
Teams.
Flyway + Spring Boot — Tutorial completo · 2025