Información general
Introducción
El objetivo de este documento es describir los procedimientos operativos relacionados con el uso de Liquibase dentro de la Plataforma CI/CD corporativa.
El manual proporciona una guía para el equipo de operaciones sobre cómo supervisar la ejecución de los pipelines que incluyen cambios en bases de datos, cómo identificar el estado de la base de datos y cómo actuar en caso de incidencias o fallos durante el despliegue.
Este documento se centra en la gestión operativa del proceso y no aborda el desarrollo de changesets ni la configuración de repositorios Liquibase, aspectos que se describen en el Manual de usuario de la herramienta de gestión de cambios en bases de datos.
Los cambios en bases de datos gestionados mediante Liquibase deben cumplir las normas y directrices establecidas en el documento normativo corporativo y en el Manual de Usuario de Liquibase, siendo estos documentos la referencia para la definición y estructuración de los cambios.
Liquibase en la Plataforma CI/CD corporativa
Liquibase se integra en la Plataforma CI/CD corporativa como mecanismo para la gestión, ejecución y control de los cambios en la base de datos asociados a las aplicaciones.
Su ejecución se realiza de forma automatizada dentro del pipeline, garantizando que los cambios en la base de datos se aplican de forma controlada, trazable y alineada con el despliegue del artefacto de aplicación.
El pipeline ejecuta Liquibase utilizando el fichero root_changelog.xml como punto de entrada, desde el cual se referencian el resto de cambios definidos en el repositorio.
Este fichero debe mantenerse como punto de entrada único y controlado para la ejecución de cambios en base de datos.
El pipeline se compone de varias fases diferenciadas, en las que Liquibase interviene principalmente en las fases de sincronización de base de datos.
Fases del pipeline
El flujo del pipeline se divide en las siguientes fases:
1. CI
En esta fase se realiza:
- la construcción del artefacto de la aplicación
- la ejecución de pruebas de calidad y seguridad (QA/Sec)
- la publicación del artefacto generado
Si la fase de CI no se completa correctamente, el pipeline finaliza sin continuar con el resto de fases.
2. PreSync
La fase PreSync es la encargada de ejecutar los cambios en la base de datos mediante Liquibase antes del despliegue del artefacto.
El flujo es el siguiente:
- Se verifica si existe la carpeta de configuración de Liquibase en el repositorio.
- Si no existe, se continúa directamente con la fase de despliegue sin ejecutar cambios en base de datos.
- Si existe, se continúa con el proceso de sincronización.
- Se guarda el TAG actual de la base de datos.
Este TAG permite identificar el estado previo de la base de datos y se utilizará en caso de rollback. - Se ejecuta el proceso de actualización de base de datos mediante Liquibase (update). Liquibase ejecuta los changesets pendientes definidos en los changelogs, en el orden establecido.
- Se evalúa el resultado de la ejecución:
- Si la ejecución es correcta:
- Se genera un nuevo TAG de base de datos con formato X.Y.Z-SNAPSHOT, representando el nuevo estado tras la aplicación de cambios.
- Se continúa con la fase de despliegue.
- Si la ejecución falla:
- Se realiza un rollback de la base de datos al último TAG válido.
- El pipeline finaliza en esta fase.
- Si la ejecución es correcta:
3. Sync
En esta fase se realiza el despliegue del artefacto de la aplicación en el entorno correspondiente.
- Se ejecuta el despliegue del artefacto.
- Se evalúa el resultado:
- Si el despliegue falla:
- Se ejecuta un rollback de la base de datos al último TAG registrado.
- El pipeline finaliza.
- Si el despliegue es correcto:
- Se continúa con la fase PostSync.
- Si el despliegue falla:
4. PostSync
La fase PostSync valida el estado final del sistema tras el despliegue y determina si el proceso puede considerarse exitoso.
El flujo es el siguiente:
- Se verifica si existe un Job de PostSync.
- Si no existe:
- Se podrán ejecutar pruebas manuales o gestionar posibles rollbacks de forma manual.
- Se requiere validación por parte del equipo de operaciones.
- Si existe:
- Se ejecuta el proceso definido.
- Si no existe:
- Se evalúa si el PostSync es bloqueante:
- PostSync bloqueante
- Se ejecutan pruebas automáticas (por ejemplo, Selenium).
- Se evalúa el resultado:
- Si falla:
- Se realiza rollback de la base de datos al último TAG.
- El pipeline finaliza.
- Si es correcto:
- Se continúa con el cierre del proceso.
- Si falla:
- PostSync no bloqueante
- Se genera directamente un TAG de versión final (X.Y.Z).
- Se ejecutan las pruebas (no bloqueantes).
- El resultado de estas pruebas no impide la finalización del pipeline.
- PostSync bloqueante
- Intervención de operaciones:
En determinados casos (por ejemplo, ejecución manual o situaciones excepcionales), el equipo de operaciones puede intervenir para:- validar el resultado
- decidir si continuar o ejecutar un rollback
- Finalización:
- Si todo es correcto, se genera el TAG final de versión (X.Y.Z) y el pipeline finaliza con estado OK.
- En caso de error, se realiza rollback y el pipeline finaliza en estado fallido.
Gestión de TAGs de base de datos
Durante el pipeline se utilizan TAGs de Liquibase para gestionar el estado de la base de datos:
- TAG anterior → punto de rollback
- TAG snapshot → estado tras PreSync
- TAG final → versión estable tras despliegue
Estos TAGs permiten:
- realizar rollback controlado
- garantizar trazabilidad
- asegurar la coherencia entre versiones
Consideraciones generales
Los cambios en base de datos se aplican siempre antes del despliegue de la aplicación.
- Cualquier error en PreSync o Deploy implica rollback automático.
- El PostSync permite validar funcionalmente el sistema antes de dar por finalizada la versión.
- El pipeline garantiza que el estado de la base de datos no sea superior a la versión del componente desplegado.
- El equipo de operaciones puede intervenir en puntos críticos del flujo.
Rol del equipo de operaciones
El equipo de operaciones tiene la responsabilidad de supervisar la ejecución de los pipelines que incluyen cambios en bases de datos y actuar en caso de incidencias.
Entre sus responsabilidades se incluyen:
- supervisar la ejecución de pipelines de despliegue
- verificar el estado de las ejecuciones de Liquibase
- identificar posibles errores durante la fase de sincronización de base de datos
- ejecutar procedimientos de rollback cuando sea necesario
- coordinar la resolución de incidencias con los equipos de desarrollo
El objetivo es garantizar que los despliegues se realicen de forma segura y que cualquier incidencia pueda resolverse de forma controlada.
Procedimientos operativos habituales
Ejecución estándar del pipeline
Durante un despliegue estándar, el pipeline ejecuta automáticamente las diferentes fases necesarias para desplegar una aplicación y aplicar los cambios de base de datos.
En condiciones normales, el equipo de operaciones únicamente debe supervisar la ejecución del pipeline y verificar que todas las fases se completan correctamente.
En particular, es importante verificar el resultado de la fase PreSync, donde Liquibase aplica los cambios de base de datos.
Si todos los changesets se aplican correctamente, el pipeline continúa con el despliegue de la aplicación.
Como validación previa a la ejecución del pipeline, el equipo de operaciones debe verificar que:
- la estructura del directorio liquibase es correcta
- el fichero root_changelog.xml referencia adecuadamente los changelogs necesarios
- los ficheros de configuración (liquibase-<entorno>.properties o .enc) están presentes y correctamente definidos
- existen subdirectorios de changelogs con nomenclatura “changelog-<versión>”
- los ficheros de changelog siguen la nomenclatura “changelog-<versión>.xml”
- los ficheros de changesets siguen la nomenclatura “changeset-<versión>-”
Identificación de la versión de la base de datos
Liquibase mantiene un registro de los cambios aplicados en la base de datos mediante tablas internas que almacenan el historial de ejecución de los changesets.
Estas tablas permiten identificar:
- qué cambios han sido aplicados
- en qué orden se han ejecutado
- el estado actual de la base de datos
Esta información puede utilizarse para verificar que la base de datos se encuentra en el estado esperado antes o después de un despliegue.
El equipo de operaciones debe verificar que la versión de la base de datos no es superior a la versión del componente desplegado.
Tablas internas de control de Liquibase
Liquibase utiliza tablas internas en la base de datos para gestionar la ejecución de cambios y garantizar la consistencia del proceso.
DATABASECHANGELOG
Esta tabla almacena el historial de ejecución de los changesets.
Permite:
- identificar qué cambios han sido aplicados
- evitar la reejecución de changesets ya ejecutados
- auditar el estado de la base de datos
DATABASECHANGELOGLOCK
Esta tabla se utiliza para gestionar bloqueos durante la ejecución de Liquibase.
Su objetivo es evitar ejecuciones concurrentes sobre la misma base de datos.
Consideraciones operativas
- Estas tablas son gestionadas automáticamente por Liquibase.
- No deben modificarse manualmente.
- Un bloqueo activo en DATABASECHANGELOGLOCK puede impedir nuevas ejecuciones de Liquibase.
Gestión de bloqueos
En caso de que un pipeline falle o se interrumpa durante la ejecución de Liquibase, puede quedar un bloqueo activo en la tabla DATABASECHANGELOGLOCK.
Esto puede provocar que nuevas ejecuciones fallen al detectar la base de datos bloqueada.
En estos casos, el equipo de operaciones debe:
- Verificar que no existe ninguna ejecución activa de pipeline sobre la base de datos.
- Revisar los logs del pipeline para identificar ejecuciones interrumpidas.
- En caso de bloqueo persistente, escalar al equipo de desarrollo o plataforma.
No se deben eliminar bloqueos manualmente sin validación previa, ya que puede comprometer la consistencia de la base de datos.
Procedimientos de rollback
Durante la ejecución del pipeline pueden producirse situaciones en las que sea necesario revertir los cambios aplicados en la base de datos. Liquibase permite realizar operaciones de rollback que restauran el estado de la base de datos a una versión anterior.
El pipeline CI/CD puede ejecutar rollbacks de forma automática en determinadas situaciones, aunque también pueden ser necesarios procedimientos de intervención manual.
La ejecución de rollback debe garantizar que la base de datos vuelve a un estado consistente y alineado con la versión del artefacto desplegado.
El resultado del rollback debe garantizar que la versión de la base de datos es coherente con la versión del componente desplegado.
Rollback por tag
Liquibase permite etiquetar el estado de la base de datos mediante tags.
Un tag representa un punto concreto en el historial de cambios aplicados y permite identificar una versión específica de la base de datos.
En caso de incidencia, es posible realizar un rollback hasta un tag determinado, restaurando la base de datos al estado que tenía en ese momento.
Este mecanismo permite recuperar rápidamente una versión estable cuando se detecta un problema durante el despliegue.
cd liquibase && liquibase --changelog-file=root_changelog.xml --classpath=mysql-connector-j-9.2.0.jar rollback <tag>Rollback tras fallo en despliegue
Si se produce un fallo durante el despliegue de una aplicación, el pipeline puede ejecutar un rollback de la base de datos para volver al estado anterior.
Este procedimiento permite mantener la coherencia entre:
- la versión de la aplicación desplegada
- la versión de la base de datos
En función de la configuración del pipeline, este rollback puede ejecutarse de forma automática o requerir intervención del equipo de operaciones.
Gestión de incidencias
Durante la ejecución del pipeline pueden producirse errores en diferentes fases del proceso.
El equipo de operaciones debe identificar en qué fase se ha producido la incidencia para aplicar el procedimiento adecuado.
Fallos en la fase PreSync
La fase PreSync es responsable de aplicar los cambios en la base de datos mediante Liquibase.
Un fallo en esta fase suele estar relacionado con:
- errores en los changesets
- conflictos con la estructura existente de la base de datos
- problemas de permisos o acceso a la base de datos
Cuando se produce un fallo en esta fase, el pipeline interrumpe la ejecución del despliegue.
- El equipo de operaciones debe revisar los logs del pipeline para identificar el changeset que ha provocado el error, verificando su nomenclatura (“changeset-<versión>-”) y que no combine operaciones de tipo DDL y DML en un mismo fichero, y coordinar la resolución con el equipo de desarrollo.
- No deben aplicarse soluciones manuales directamente sobre la base de datos sin coordinación con el equipo de desarrollo.
Fallos en la fase Deploy
La fase Deploy se encarga de desplegar el artefacto de la aplicación en el entorno correspondiente.
Si el despliegue falla después de haberse aplicado cambios en la base de datos, puede ser necesario ejecutar un rollback para restaurar el estado anterior.
El equipo de operaciones debe verificar:
- si el pipeline ha ejecutado automáticamente el rollback
- si la base de datos ha quedado en un estado consistente
- si es necesario realizar alguna intervención adicional
Fallos en la fase PostSync
La fase PostSync puede incluir la ejecución de pruebas posteriores al despliegue.
Si estas pruebas fallan, el pipeline puede indicar que el despliegue no ha sido satisfactorio.
En estos casos, el equipo de operaciones debe evaluar la situación y decidir si es necesario revertir el despliegue o coordinar una solución con el equipo de desarrollo.
Escenarios especiales
En determinadas situaciones pueden producirse escenarios que requieren un análisis adicional por parte del equipo de operaciones.
Cambios no gestionados por Liquibase
En algunos casos pueden detectarse cambios en la base de datos que no han sido gestionados mediante Liquibase.
Esto puede ocurrir cuando se han realizado modificaciones manuales directamente en la base de datos.
Este tipo de situaciones puede provocar inconsistencias entre el estado real de la base de datos y el historial de cambios registrado por Liquibase.
Estos cambios incumplen las normas establecidas y deben ser regularizados mediante changesets.
Inconsistencias entre artefacto y base de datos
También pueden producirse inconsistencias cuando la versión del artefacto desplegado no coincide con la versión de la base de datos.
Este tipo de situaciones puede ocurrir si:
- un despliegue ha fallado parcialmente
- se han aplicado cambios manuales en la base de datos
- se ha realizado un rollback incompleto
El equipo de operaciones debe verificar el estado del sistema y coordinar con los equipos responsables para restaurar la coherencia entre aplicación y base de datos.
Buenas prácticas operativas
Para garantizar un funcionamiento correcto del pipeline y minimizar incidencias relacionadas con cambios en bases de datos, se recomienda seguir las siguientes buenas prácticas.
Qué hacer
- supervisar siempre la ejecución de los pipelines de despliegue
- revisar los logs en caso de fallo durante la ejecución de Liquibase
- verificar el estado de la base de datos tras despliegues con cambios estructurales
- coordinar con el equipo de desarrollo la resolución de incidencias
- verificar que los changelogs y changesets cumplen la nomenclatura definida en la normativa
Qué no hacer
- no realizar cambios manuales en bases de datos gestionadas por Liquibase
- no modificar changesets que ya han sido ejecutados
- no aplicar soluciones temporales que puedan generar inconsistencias en el historial de cambios
Cuando escalar
Debe escalarse la incidencia al equipo de desarrollo cuando:
- un changeset provoca errores durante la ejecución
- el rollback no puede ejecutarse correctamente
- se detectan inconsistencias en el historial de cambios
- el estado de la base de datos no coincide con la versión de la aplicación desplegada
Uso de credenciales encriptadas en Liquibase
Los pipelines CI/CD utilizan archivos liquibase-<entorno>.properties.enc encriptados para gestionar de forma segura las credenciales de acceso a base de datos.
Estos archivos:
- se almacenan en los repositorios en formato encriptado (.enc)
- son generados por los equipos de desarrollo
- son descifrados automáticamente durante la ejecución del pipeline