Flyway y Liquibase

Flyway y Liquibase son los dos ejecutores de migraciones basados en JVM más comunes para PostgreSQL en pipelines empresariales. Ambos rastrean los cambios aplicados, soportan CI y se integran con Spring y la orquestación de lanzamientos.

Receta

# Flyway
flyway -url=jdbc:postgresql://localhost:5432/myapp \
  -user=app_migrator -password="$DB_PASS" \
  -locations=filesystem:db/migration \
  migrate
 
# Liquibase
liquibase --url=jdbc:postgresql://localhost:5432/myapp \
  --username=app_migrator --password="$DB_PASS" \
  --changeLogFile=db/changelog/db.changelog-master.yaml \
  update

Cuándo usar esto: Múltiples destinos de despliegue, requisitos de auditoría, validación de checksums y equipos ya estandarizados en herramientas JVM.

Ejemplo de Trabajo

Diseño de Flyway:

db/migration/
  V1__baseline.sql
  V2__add_orders.sql
  V3__orders_index_concurrent.sql  # nota: ejecutar fuera de txn - ver documentación

-- V2__add_orders.sql
SET ROLE app_owner;
CREATE TABLE app.orders (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  total_cents integer NOT NULL
);
RESET ROLE;

Changelog maestro de Liquibase:

# db/changelog/db.changelog-master.yaml
databaseChangeLog:
  - include:
      file: changes/001-baseline.sql
      relativeToChangelogFile: true
  - include:
      file: changes/002-orders.yaml
      relativeToChangelogFile: true

# changes/002-orders.yaml
databaseChangeLog:
  - changeSet:
      id: 002-orders
      author: data-team
      changes:
        - sqlFile:
            path: 002-orders.sql
            relativeToChangelogFile: true
      rollback:
        - sql: DROP TABLE IF EXISTS app.orders;

Lo que esto demuestra:

• Flyway: un archivo SQL por versión, nomenclatura lineal V{n}__
• Liquibase: changelog YAML/XML con bloques de rollback opcionales por changeSet
• Ambos registran el historial en tablas de metadatos automáticamente

Profundización

Comparación

Configuraciones Específicas de PostgreSQL

# flyway.conf
flyway.postgresql.transactional.lock=false
flyway.cleanDisabled=true

# Liquibase changeSet para índice CONCURRENTE
- changeSet:
    id: idx-concurrent
    runInTransaction: false
    changes:
      - sql:
          sql: CREATE INDEX CONCURRENTLY idx_orders_created ON app.orders (created_at);

• CREATE INDEX CONCURRENTLY no puede ejecutarse en una transacción.
• Deshabilitar clean en Flyway de producción: elimina todos los objetos.
• Usar lock_timeout y statement_timeout en las migraciones SQL (ver reglas de seguridad).

Integración CI

flyway validate   # detección de deriva de checksums
flyway info       # pendientes vs aplicadas
liquibase status
liquibase validate

Trampas

• Editar archivo de migración aplicado - El desajuste de checksum bloquea el despliegue. Solución: Nueva migración directa V4__fix.sql, nunca reescribir V2.
• Índice concurrente dentro de una transacción - El valor predeterminado de Flyway lo envuelve en una transacción; la migración falla. Solución: executeInTransaction=false por migración (Flyway) o runInTransaction: false (Liquibase).
• Baja confianza en el rollback de Liquibase - El SQL de rollback no probado se corrompe. Solución: Tratar el rollback solo para simulacros; preferir correcciones directas de expansión/contracción.
• Migrador superusuario - Concesiones y valores predeterminados de RLS incorrectos. Solución: app_migrator con SET ROLE app_owner.
• Historial diferente por entorno - Hotfix seleccionado solo en producción. Solución: Mismo SHA de git a través del pipeline de desarrollo/staging/producción.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Migraciones - principios de SQL versionado
• DDL sin tiempo de inactividad - operaciones concurrentes
• Estrategia de Rollback - política de solo avance

Versiones de Stack: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x, y PostGIS 3.5+.