CI/CD de migraciones de esquema (Flyway/Liquibase)

Síntoma

Objetivo: gestionar los cambios de esquema de la base de datos con archivos de migración versionados; aplicarlos de forma automática pero controlada dentro de CI/CD con Flyway o Liquibase.

1. Cree archivos de migración versionados (Vxxx__name.sql)

Escriba cada cambio de esquema en un archivo con nombre y un número de versión creciente; la convención de Flyway es V<version>__<description>.sql (p. ej., V1__initial_schemas.sql, V2__orders_table.sql). Estos archivos se guardan en Git y se aplican en orden de versión. Las migraciones aplicadas se registran en una tabla de seguimiento (flyway_schema_history en Flyway), de modo que cada migración se ejecuta exactamente una vez.

PostgreSQL

-- V2__orders_table.sql
CREATE TABLE orders (
  id       bigserial PRIMARY KEY,
  amount    numeric(12,2) NOT NULL,
  created_at   timestamptz DEFAULT now()
);

2. Preserve la inmutabilidad con checksums

Flyway/Liquibase almacenan el checksum de cada migración aplicada. Si después edita un archivo ya aplicado, el checksum deja de coincidir y la herramienta falla. Regla: NUNCA edite una migración aplicada; haga la corrección con un nuevo archivo de versión. Esto garantiza que todos los entornos (dev/staging/prod) compartan el mismo historial.

PostgreSQL

# repair on checksum mismatch (use with care):
flyway repair
# the right way: add the change in a new Vx file

3. Establezca una baseline en una base de datos existente

Use baseline al conectar la herramienta de migración a una base de datos ya poblada y sin historial; toma el estado actual como 'versión inicial' y no intenta recrear los objetos existentes. Se aplican las migraciones posteriores a baselineVersion. En un entorno creado desde cero no se necesita baseline; las migraciones se ejecutan desde V1 en adelante.

PostgreSQL

flyway baseline -baselineVersion=1 -baselineDescription="existing schema"

4. Migre automáticamente en el pipeline de CI

Ejecute la herramienta de migración en un paso de CI para aplicar los cambios automáticamente en las bases de datos de test y staging; el comando migrate ejecuta solo los archivos nuevos (no aplicados) y es idempotente. Aplicar primero la migración en una base de datos temporal/efímera y validarla detecta el SQL defectuoso antes de que llegue a prod. El esquema debe migrarse ANTES de desplegar el código de la aplicación (con cambios compatibles con versiones anteriores).

PostgreSQL

# CI step (Flyway)
flyway -url=jdbc:postgresql://staging/appdb \
  -user=ci -password=$PW migrate

MySQL

flyway -url=jdbc:mysql://staging/appdb \
  -user=ci -password=$PW migrate

5. Agregue una puerta de aprobación manual para prod

Test/staging son automáticos, pero haga que el migrate en prod requiera aprobación manual; agregue un paso de 'approval gate' (aprobación manual) en CI/CD. Antes de la aprobación, muestre qué migraciones se ejecutarán con 'flyway info' o 'liquibase status'. Haga siempre un backup reciente antes de aplicar en prod para poder revertir si algo sale mal.

PostgreSQL

# what will run before approval?
flyway info
# liquibase equivalent:
liquibase status --verbose

6. Defina la reversibilidad y una estrategia de rollback

Flyway Community no tiene undo automático; adopte el principio de migraciones solo hacia adelante (forward-only): en lugar de deshacer un error, escriba una nueva migración que lo corrija. Los changesets de Liquibase pueden definir un bloque rollback y revertirse con 'liquibase rollback'. La estrategia más sólida: mantener los cambios pequeños y compatibles con versiones anteriores, hacer un backup antes de las operaciones de riesgo (eliminar columnas) y preparar un plan de rollback por escrito.

PostgreSQL

-- Liquibase rollback example (inside a changeset)
--changeset dev:2
CREATE TABLE orders (...);
--rollback DROP TABLE orders;