El objetivo del siguiente documento está enfocado en mostrar la estructura de directorio de la herramienta Liquibase.

=== CONTROL DE VERSIONES DEL DOCUMENTO

​

​

Indice

• 1 - Propósito
• 2 - Requisitos
• 3 - Compatibilidad de liquibase
• 4 - Estructura del proyecto
• 5 - Flujo de ejecución de pipelines para update y rollback
• 6 - Ejecucion en Jenkins por entorno
• 7 - Ejecucion de Rollback
• 8 - Comentarios

1. Propósito

Liquibase es una herramienta de control de versiones de base de datos que permite a los equipos de desarrollo de software mantener un registro de los cambios en la estructura de sus bases de datos. Al usar Liquibase como parte del pipeline de Jenkins, los equipos pueden asegurarse de que los cambios en la base de datos se integren en el proceso de integración continua, lo que ayuda a reducir errores y a mejorar la calidad del software.

2. Requisitos

• Accesos a bitbucket para la actualización de fuentes
• Accesos a la Heramienta Devops: Jenkins

3. Compatibilidad de liquibase

Liquibase es compatible con la mayoría de sistemas ó gestores de base de datos, en el caso de querer usar uno diferente, existe la posibilidad de usar drivers.

Nosotros hemos validado el driver para Oracle y PostgreSQL:

• oracle.jdbc.OracleDriver
• org.postgresql.Driver

4. Estructura del proyecto

Para garantizar una correcta integración del pipeline de Liquibase en un repositorio de código, es esencial que el repositorio cumpla con una estructura específica que siga los lineamientos del frente de DevOps.

• cfg
• src/tables
• .gitignore
• README.md
• VERSION
• db.changelog-root.xml
• liquibase.properties

cfg/: Este directorio alberga los siguientes archivos:

• devops.properties: se definen las propiedades del flujo del pipeline de Liquibase.

• liquibase-[entorno]: se definen las credenciales y valores necesarios para conectarse a la BBDD. Además, este archivo tiene una funcionalidad adicional para obtener los valores directamente desde Jenkins (Credentiales).

• db.changelog-[action]: es el archivo de configuración principal que se utiliza para definir los cambios que se aplicarán en la base de datos utilizando el pipeline de Liquibase. Este archivo referencia a otros archivos de cambio, que contienen la información específica sobre los cambios que se aplicarán en la base de datos. Al utilizar este archivo, se garantiza una ejecución ordenada y confiable de los scripts de actualización de la base de datos.

• src/: En este directorio es encuentran los archivos de la base de datos que se utilizarán para las actualizaciones. Solo se usará archivos en formato SQL. La estructura está ordenada de tal manera que de acuerdo al objeto a manipular existe un directorio. Por ejemplo, existen directorios para tablas, procedimientos almacenados, vistas, funciones, rollback, etc.

• VERSION: Este archivo se utiliza para llevar un registro de las versiones de la base de datos que se van actualizando. Este archivo es esencial para garantizar que los cambios se apliquen en el orden correcto y evitar errores.

Repositorio de solución Liquibase

• https://bitbucket.org/telefonica-peru/liquibase-genesis-demo-template

Estructura de los directorios

La estructura de los directorios sería de la siguiente manera:

Contenido de un archivo .sql:

Cada archivo .sql debe comenzar con el comentario:

--liquibase formatted sql

Cada archivo changeset en el formato SQL comienza con un comentario de la forma: -- changeset autor:id

Contenido de archivos changelog:

• Para proceso Update: db.changelog-update.xml:

• Para proceso Rollback: db.changelog-rollback.xml

Nota: Es importante tener en cuenta que, si bien esta estructura es recomendada, puede variar según los requisitos específicos del proyecto. En general, lo más importante es garantizar que los archivos de la base de datos estén organizados y sean fáciles de encontrar, y que la configuración del pipeline se defina claramente en el archivo devops.properties.

5. Flujo de ejecución de pipelines para update y rollback

6. Ejecucion en jenkins por entorno

Para la ejecución de los pipelines de update de base de datos, es necesario que previamente se haya creado el pipeline mediante Gencli, colocando en un repositorio de Bitbucket las sentencias a ejecutar mediante este pipeline.

Los repositorios para estos pipelines deben cumplir con la siguiente nomenclatura:

• db-[app]-[bd] Un ejemplo de nombre de repositorio: db-genesis-genesis

Los pipelines para actualización con Liquibase se encuentran en la siguiente ruta:

• [team] _ [entorno]/FastData/db-[app]-[db] Un ejemplo de la ruta del pipeline: genesis_dev/FastData/db-genesis-genesis

  En entorno desarrollo el pipeline podra seleccionar una rama feature (ejemplo : feature/una_rama_ejemplo) en caso no se seleccione una rama feature por defecto usara la rama develop En entorno certificacion se puede seleccionar una rama tipo hotfix (ejemplo : hotfix/una_rama_ejemplo) en caso no se seleccione una rama feature por defecto usara la rama develop Para entorno productivo se debe previamente ubicar la rama creada desde certificacion Una vez ubcada la rama creada para el release se debe de ingresar en la casilla de RELEASE_BRANCH

7. Ejecucion de Rollback

En cada entorno existe una carpeta Rollback en donde se puede realizar el rollback tanto por carpeta como por archivo de las sentencias ejecutadas previamente por el pipeline de update.

Para la ejecución del pipeline se debe de ingresar a la siguiente ruta: [team] _ [entorno]/Rollback/

En el cual existiran 2 pipelines para el rollback de Liquibase:

• RollbackLiquibase
• RollbackLiquibaseFile
  ​

Para la ejecución se debe de realizar lo siguiente:​

• Hacer click en "Construir con parametros".​
• Indicar el nombre del pipeline de actualización de liquibase. (El nombre del pipeline que se ejecuto en el paso 6)​
• Indicar la rama que se utilizará para la reversión.​

En caso de hacer un rollback de archivo (RollbackLiquibaseFile), adicional se solicitará indicar el nombre del archivo que va a ejecutar para la reversión. ​

8. Comentarios

Si un ambiente tiene más de dos servidores de BBDD por favor comunicarse con el equipo de DevOps.