Verificando autenticación…

Saltar al contenido principal

Template Liquibase

Propósito y Alcance​

Este proyecto provee una plantilla estandarizada y un conjunto de herramientas para gestionar y aplicar cambios de esquema en bases de datos PostgreSQL utilizando Liquibase. Está diseñado para facilitar el versionado de la base de datos, la ejecución de migraciones de forma controlada tanto en entornos locales como en pipelines de CI/CD.

Principales Funcionalidades:

  • Definición de cambios de base de datos (DDL y DML) mediante archivos de changelog en formato YAML.
  • Ejecución de migraciones en entornos de desarrollo local contra una instancia de PostgreSQL.
  • Integración con pipelines de CI/CD (Jenkins y GitLab CI) para automatizar la aplicación de migraciones.
  • Despliegue de migraciones en contenedores Docker, facilitando la ejecución en entornos como Google Kubernetes Engine (GKE) y Google Cloud Run.
  • Conexión segura a instancias de Google Cloud SQL mediante el uso de Cloud SQL Proxy.

El alcance cubre desde la creación y modificación de tablas hasta la carga de datos iniciales o de configuración.

Arquitectura​

El flujo de trabajo y los componentes principales de este template de Liquibase son:

  1. Desarrollo de Cambios: Los desarrolladores definen los cambios de esquema o datos en archivos *.yaml siguiendo la sintaxis de Liquibase. Estos archivos se organizan en una estructura de directorios (database/changelog/tables/, database/changelog/data/).
  2. Pruebas Locales: Los cambios pueden ser probados localmente ejecutando Liquibase CLI contra una instancia de PostgreSQL configurada para desarrollo.
  3. Control de Versiones: Los archivos de changelog se versionan en un repositorio Git.
  4. Construcción de Imagen Docker: Un Dockerfile está provisto para construir una imagen que contiene:
    • Liquibase.
    • Los scripts de changelog del proyecto.
    • Cloud SQL Proxy (para conectarse a instancias de Google Cloud SQL).
  5. Integración Continua / Despliegue Continuo (CI/CD):
    • Jenkins: Un Jenkinsfile define una pipeline (liquibase-migration) que presumiblemente construye la imagen Docker y la ejecuta para aplicar las migraciones en el entorno destino.
    • GitLab CI: Un archivo .gitlab-ci.yml se integra con pipelines de LATAM para desplegar los cambios, específicamente para Cloud Run ($LATAM_PIPELINE_CLOUD_RUN_DEPLOY).
  6. Ejecución en Entorno Destino (GKE/Cloud Run):
    • La imagen Docker se ejecuta como un Pod en GKE (definido en deploy/gke/deployment.yaml.erb) o como un servicio en Cloud Run (definido en deploy/run/*.yaml.erb).
    • Dentro del contenedor, el Cloud SQL Proxy establece una conexión segura a la base de datos.
    • Liquibase ejecuta los comandos validate, releaseLocks y update contra la base de datos destino, aplicando los cambios pendientes.

Este enfoque asegura que los cambios en la base de datos sean consistentes, versionados y aplicados de manera automatizada y segura en los diferentes entornos.

Tecnologías y Dependencias​

  • Liquibase: Herramienta principal para la gestión de migraciones de bases de datos.
  • PostgreSQL: Sistema de gestión de bases de datos relacional para el cual están diseñados los changelogs.
  • Docker: Para la contenerización de la aplicación Liquibase y sus dependencias.
  • YAML: Formato utilizado para escribir los changelogs de Liquibase.
  • Google Cloud SQL Proxy: Para conexiones seguras a instancias de PostgreSQL en Google Cloud.
  • Jenkins: Sistema de CI/CD utilizado para orquestar despliegues (vía Jenkinsfile).
  • GitLab CI: Sistema de CI/CD utilizado para orquestar despliegues a Cloud Run (vía .gitlab-ci.yml).
  • Google Kubernetes Engine (GKE): Plataforma de orquestación de contenedores, uno de los posibles entornos de despliegue.
  • Google Cloud Run: Plataforma serverless para ejecutar contenedores, otro posible entorno de despliegue.
  • Bash/Shell: Utilizado para scripts de ejecución en el Dockerfile y en instrucciones locales.
  • Red Hat Universal Base Image (UBI) 8: Imagen base para el Dockerfile (redhat_ubi_8_liquidbase_4).

Configuración Local​

Sigue estos pasos para ejecutar las migraciones de Liquibase en tu entorno local.

Prerrequisitos​

  • Liquibase CLI: Debe estar instalado y accesible en tu PATH. Puedes encontrar instrucciones de instalación aquí.
  • Driver JDBC de PostgreSQL: Descarga el driver JDBC para PostgreSQL (un archivo .jar) y colócalo en una ubicación accesible para Liquibase (e.g., en una carpeta lib/ dentro del proyecto, o en el directorio lib de tu instalación de Liquibase). El readme.md original sugiere una ruta como ../lib/postgresql.jar relativa a la carpeta database.
  • Instancia de PostgreSQL: Necesitas una instancia de PostgreSQL corriendo y accesible.

Pasos de Configuración​

  1. Crear proyecto:
    • Acceder a: https://app.getport.io/self-serve
    • Seleccionar scaffolding Liquibase
    • Seleccionar deployment GKE
    • Seleccionar Sample_data
    • Si deseas subir el proyecto a gitlab selecciona Push to GitLab y registra el group id de gitlab

🔖 Nota​

El nombre del componente SIEMPRE debe comenzar con liquibase ejemplo: liquibase-migration-nombre-mi-componente
  1. Ejecucion local

Instalar liquibase​

Mac​

brew install liquibase

linux​

Instalation Instruction here

Windows​

Instalation Instruction here

Configurar base de datos​

#Create a role
CREATE ROLE newuser WITH LOGIN PASSWORD 'password';
ALTER ROLE newuser CREATEDB;

#with the newuser create a new database
create database template;

#Connect to the database
\connect template

#Create the schmea
CREATE SCHEMA "template" AUTHORIZATION newuser;

#Set default schemma to template
SET search_path TO template;
SHOW search_path;

#list tables
\dt

Crear tabla​

#Exportar variables

export DATABASE_USERNAME=newuser
export DATABASE_PASSWORD=password
export DATABASE_URL=jdbc:postgresql://127.0.0.1:5432/template?currentSchema=template

Ejecutar liquibase​

cd liquibase-migration/database
liquibase --classpath=../lib/postgresql.jar --changeLogFile=changelog-master.yaml --url=${DATABASE_URL} \
                  --username=${DATABASE_USERNAME} --password=${DATABASE_PASSWORD} --logLevel=${LOG_LEVEL:-info} update

Unlock Database​

liquibase --classpath=../lib/postgresql.jar --changeLogFile=changelog-master.yaml --url=${DATABASE_URL} \
                  --username=${DATABASE_USERNAME} --password=${DATABASE_PASSWORD} --logLevel=${LOG_LEVEL:-info} releaseLocks