Schema Migration — esencia, tipos y herramientas de migración de esquemas de BD

Qué es Schema Migration

Schema Migration es la práctica de gestionar cambios en la estructura de la base de datos a través de archivos versionados que se aplican secuencialmente a diferentes entornos. Cada archivo contiene un conjunto de comandos SQL: crear una tabla, agregar una columna, modificar un índice o actualizar restricciones. La herramienta de migración realiza un seguimiento de las versiones aplicadas y garantiza que cada cambio se ejecute exactamente una vez.

A diferencia de Data Migration, que transfiere el contenido de las tablas, Schema Migration solo gestiona la estructura (operaciones DDL). Esta es una distinción fundamental: Schema Migration se ejecuta antes que Data Migration, creando el esquema de destino en el que luego se cargan los datos. Según Redgate (2024), el 62% de los incidentes en bases de datos de producción están relacionados con cambios manuales en el esquema sin scripts de migración.

Versionado de migraciones

Cada Schema Migration recibe un identificador único — generalmente una versión (V1, V2) o una marca de tiempo. La herramienta almacena una lista de migraciones aplicadas en una tabla especial (flyway_schema_history, alembic_version). Al iniciar, compara la lista con los archivos en el classpath y aplica solo las nuevas. La idempotencia es una propiedad clave: volver a ejecutar no causa efectos secundarios.

Tipos de cambios de esquema

Operaciones típicas de Schema Migration: crear tablas (CREATE TABLE), agregar columnas (ALTER TABLE ADD COLUMN), cambiar tipos, crear índices, agregar claves foráneas y actualizar secuencias. Las migraciones más complejas incluyen renombrar columnas conservando datos, dividir una tabla en varias y replicar un esquema entre shards.

Por qué se necesita la migración de esquemas de BD

Sin Schema Migration, los desarrolladores modifican la base de datos manualmente — editan DDL en la consola, agregan columnas en el entorno dev y las copian a staging de memoria. El resultado: desviación del esquema entre entornos, pérdida de cambios durante el despliegue y migraciones rotas en producción. Schema Migration resuelve tres problemas clave: consistencia, reproducibilidad y auditoría.

Consistencia entre entornos

Cuando la estructura de la base de datos está descrita en código, es idéntica en dev, staging y producción. Un desarrollador no puede olvidar aplicar un cambio — la herramienta ejecutará todas las migraciones omitidas secuencialmente. Si falta una columna en producción pero el código la requiere, la aplicación fallará con un error. La verificación automática elimina este escenario.

Reproducibilidad para nuevos desarrolladores

Un nuevo miembro del equipo ejecuta flyway migrate y obtiene el esquema actual en segundos — sin un dump de producción ni consultas DDL manuales. Esto es especialmente importante en una arquitectura de microservicios, donde cada servicio tiene su propia base de datos y el esquema se construye a partir de docenas de migraciones. La reproducibilidad total reduce la incorporación de días a minutos.

Auditoría de cambios

Cada Schema Migration se almacena en el sistema de control de versiones junto con el código de la aplicación. Puede abrir una Pull Request, ver los comandos SQL exactos del cambio de esquema y realizar una revisión de código. En caso de incidente, es fácil determinar qué migración se aplicó última y quién fue su autor. El historial de Git proporciona un rastro completo de los cambios en la base de datos durante todo el proyecto.

Herramientas de migración de esquemas

Existen docenas de herramientas de Schema Migration para diferentes lenguajes y plataformas. La elección depende del stack tecnológico, el formato de descripción de las migraciones y los requisitos de rollback. Veamos las principales categorías y herramientas populares.

Cómo elegir una herramienta

Para stacks Java/Kotlin — Flyway como el más ligero y predecible. Para proyectos con rollbacks frecuentes — Liquibase, que tiene rollback integrado en su arquitectura. Para Python/Django — Alembic como herramienta estándar de SQLAlchemy. Para startups sin ingeniero DevOps — elija la herramienta con menos configuración: Flyway solo requiere un archivo de script y el comando migrate.

Soluciones comerciales

Además de las herramientas open-source, existen soluciones comerciales: Redgate SQL Change Automation, Datical DB y DBmaestro. Proporcionan comparación visual de esquemas, resolución automática de conflictos e integración con pipelines CI/CD. Sin embargo, para la mayoría de los proyectos, Flyway o Alembic cubren el 100% de las necesidades sin licencias adicionales.

Migración con Flyway

Veamos un ejemplo práctico de Schema Migration en Kotlin con Flyway. Crearemos una migración que agregue una tabla orders a una base de datos PostgreSQL. Flyway crea automáticamente la tabla flyway_schema_history y realiza un seguimiento de las versiones aplicadas.

-- V1__Create_Orders_Table.sql
CREATE TABLE orders (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id         UUID NOT NULL,
    total_amount    DECIMAL(10,2) NOT NULL,
    currency        VARCHAR(3) NOT NULL DEFAULT 'USD',
    status          VARCHAR(20) NOT NULL DEFAULT 'pending',
    created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id)
);

Conexión de Flyway en un proyecto Kotlin a través de la configuración dataSource. Después de la configuración, el comando flyway:migrate aplicará todas las nuevas migraciones del classpath.

// FlywayConfig.kt — configuración de Flyway en Spring Boot
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.flywaydb.core.Flyway

@Configuration
class FlywayConfig {
    @Bean
    fun flyway(dataSource: DataSource): Flyway {
        return Flyway.configure()
            .dataSource(dataSource)
            .locations("classpath:db/migration")
            .baselineOnMigrate(true)
            .load()
    }
}

Alembic para proyectos Python

Alembic es una herramienta de Schema Migration para Python construida sobre SQLAlchemy. Su característica clave es la autogeneración de scripts mediante la comparación del modelo SQLAlchemy con el esquema actual de la base de datos. Alembic es adecuado para proyectos Django, FastAPI y Flask.

Inicialización y creación de una migración

Después de la inicialización (alembic init alembic) y la configuración de la cadena de conexión, el comando alembic revision --autogenerate escanea los modelos SQLAlchemy y genera un script de migración. El desarrollador solo necesita revisar el código generado y aplicarlo mediante alembic upgrade head. Autogenerate ahorra horas de escritura manual de DDL.

# models.py — modelo SQLAlchemy para autogeneración
from sqlalchemy import Column, Integer, String, DateTime, Enum
from sqlalchemy.orm import DeclarativeBase
import enum

class OrderStatus(enum.Enum):
    pending = "pending"
    paid = "paid"
    shipped = "shipped"

class Base(DeclarativeBase):
    pass

class Order(Base):
    __tablename__ = "orders"
    id = Column(Integer, primary_key=True)
    status = Column(Enum(OrderStatus), nullable=False)
    created_at = Column(DateTime, nullable=False)

Mejores prácticas de migración de esquemas

Los equipos experimentados han desarrollado un conjunto de reglas de Schema Migration que reducen el riesgo de fallos y simplifican la depuración. Seguir estas prácticas es una señal de una cultura de ingeniería madura. Cinco reglas clave cubren el diseño, las pruebas y el despliegue de migraciones.

Una migración — un cambio

Cada Schema Migration debe hacer exactamente un cambio lógico: crear una tabla, agregar una columna o modificar un índice. Mezclar varias operaciones en una migración complica el rollback — si la segunda operación falla, la primera ya se aplicó y debe revertirse por separado. Pasos pequeños son la base de migraciones confiables.

Nunca editar migraciones publicadas

Una vez que una migración se ha aplicado a producción, no se puede modificar — solo se puede crear una nueva migración que corrija el problema. Editar una migración publicada rompe el rastreador: los desarrolladores con otra base de datos verán una discrepancia de hash. Las migraciones inmutables garantizan un comportamiento predecible en todos los entornos.

Pruebas en una copia de producción

Antes de aplicar una Schema Migration en producción, ejecútela en una copia de los datos de producción. El objetivo es comprobar la velocidad de ejecución, la presencia de bloqueos de tabla y la corrección de los cambios. Para tablas grandes, ALTER TABLE puede bloquear escrituras durante horas — las pruebas lo identificarán con antelación. Staging con un dump de producción es un paso obligatorio.

Evitar NOT NULL para nuevas columnas

Una nueva columna sin valor predeterminado con NOT NULL es una causa común de fallo de migración. En los registros existentes, el valor será NULL, y NOT NULL provocará un error. Mejor práctica: cree la columna con un valor predeterminado y nullable, luego agregue NOT NULL en una migración separada después de completar los datos.