Migraciones de BD en legado sin ORM: estructura y práctica

# Sistema de Migración de Bases de Datos para Proyectos Legados sin ORM

En sistemas legados sin ORM, la gestión de migraciones de scripts DDL/DML requiere un control estricto. Este enfoque organiza un repositorio y tablas de estado para aplicar cambios de forma consistente en entornos de pruebas y producción. Garantiza trazabilidad, integridad de datos y despliegues predecibles en bases de datos relacionales con cumplimiento ACID.

El método reduce el código repetitivo en los scripts, automatiza la validación y el registro. Los scripts se dividen en cuatro tipos: inicialización, baseline, versionados y repetibles. Cada tipo sigue reglas específicas para evitar duplicados y mantener la monotonicidad de versiones.

Estructura del Repositorio Git

Los scripts se agrupan por tipo y se aplican en un orden fijo:

• Inicialización de entorno — se ejecuta una sola vez para crear usuarios, roles, bases de datos y esquemas. Específico del entorno (pruebas/prod), ejecutado vía psql.
• Baseline — se ejecuta una sola vez en un esquema vacío para establecer la versión inicial de producción y las tablas de control.
• Versionados — se aplican secuencialmente por versiones enteras ascendentes, solo una vez, dentro de una transacción que registra marca de tiempo y usuario.
• Repetibles — se aplican si cambia el SHA256 o no existe registro, después de los scripts versionados, para vistas/procedimientos/triggers sin modificaciones de datos.

Tipos de objetos:

• Inicialización: usuarios, roles, bases de datos, esquemas.
• Baseline: tablas, datos, vistas, procedimientos, triggers.
• Versionados: cambios de esquema, migraciones de datos.
• Repetibles: vistas, procedimientos, triggers.

Esta estructura se inspira en Flyway, pero está adaptada para procesos manuales sin herramientas externas.

Tablas de Estado en el Esquema

Cada esquema recibe tablas de servicio para el seguimiento:

• dbmigration_versions (version_id, is_baseline, created_at, created_by, created_from) — rastrea el historial de scripts baseline y versionados.
• dbmigration_repeatable (sha256sum, relative_path, created_at, created_by, created_from) — rastrea scripts repetibles, permitiendo reaplicación ante cambios.

Estas tablas imponen verificaciones antes de ejecutar scripts: un script se ejecuta solo si no existe registro o ha cambiado el checksum. Los logs capturan usuario y marca de tiempo para auditorías completas.

Despliegues en Desarrollo

En CI/CD (pipelines de GitLab), clona la rama con cambios y, para cada esquema:

$ git clone <url con cambios de esquema de base de datos>
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <db> --user <user_name> schema1 ./db/schema1
$ USER_PASSWORD=topsecret123 dbmigration.py update --host <host> --port <port> --dbname <db> --user <user_name> schema2 ./db/schema2

Esto aplica automáticamente scripts pendientes preservando los datos.

Proceso en Producción

Soporta despliegues en caliente con cero tiempo de inactividad. Preprobado en UAT con pruebas de humo.

Pasos:

• Extrae el archivo: tar xzvf system-x.y.z.tar.gz.
• Para el esquema: cd system-x.y.z/schema1.
• Genera script de migración: USER_PASSWORD=topsecret123 dbmigration.py verify --host <host> --port <port> --dbname <db> --user <user_name> --build-update-script ./schema1_migrate.sql schema1 ./db/schema1.
• Revisa schema1_migrate.sql en busca de cambios disruptivos.
• Aplica: PGPASSWORD=topsecret123 psql -h <host> -p <port> -U <user> -d <database> -v schema_name=<schema1> -f "schema1_migrate.sql".

Repite para cada esquema. El modo verify previsualiza cambios sin aplicarlos.

Prácticas Clave

• Arreglar hacia adelante: Usa nuevas migraciones para corregir errores en lugar de rollback, preservando datos.
• Cambios no disruptivos: Agrega tablas/columnas primero, elimínalas post-lanzamiento si no se usan. Permite coexistencia multi-versión en la misma BD.
• Seguimiento a nivel de esquema: Versiones por esquema, no por base de datos.
• Pre-verificaciones: Genera scripts para revisión.
• Preservación de datos: Actualizaciones incrementales evitan drop/recreate.

Lecciones Clave

• El seguimiento automatizado elimina código repetitivo manual y errores en scripts.
• Versiones monotónicas con transacciones aseguran estados consistentes.
• Soporte para hotfixes entre versiones (prod/UAT/dev) vía scripts versionados.
• Auditorías completas desde tablas: quién/cuándo/qué se aplicó.
• Funciona con cualquier SGBD relacional compliant con ACID.

— Editorial Team