Migraciones de Base de Datos de Forma Segura

Visión General

Las migraciones de base de datos evolucionan el esquema a medida que tu aplicación cambia. Migraciones inseguras — como agregar una columna no-nula a una tabla grande o eliminar una columna aún referenciada por código viejo — pueden causar downtime, pérdida de datos o fallos de despliegue. El siguiente enfoque cubre patrones de migración segura usando Alembic (Python), Knex.js (JavaScript) y Flyway (Java), más estrategias de despliegue sin downtime.

Cuándo Usar

Usa este recurso cuando:

• Despliegues cambios de esquema a una base de datos productiva con tráfico en vivo. Consulta Database Migrations para panorama de herramientas.
• Necesites agregar, renombrar o remover columnas sin romper aplicaciones en ejecución. Consulta Input Validation para seguridad de schema.
• Migres datos entre tablas o formatos. Consulta Data Validation para verificación de integridad.
• Quieras establecer un plan de rollback antes de ejecutar cualquier migración. Consulta Retry Logic para patrones de recuperación.

Solución

Python (Alembic)

# migración: agregar columna nullable, backfill, luego hacer non-nullable
from alembic import op
import sqlalchemy as sa
from sqlalchemy.sql import table, column

revision = "abc123"
down_revision = "xyz789"

def upgrade():
    # Paso 1: Agregar como nullable para que filas existentes no fallen
    op.add_column("users", sa.Column("display_name", sa.String(255), nullable=True))

    # Paso 2: Backfill con valor por defecto
    users = table("users", column("display_name"))
    op.execute(users.update().values(display_name="Usuario sin nombre"))

    # Paso 3: Ahora seguro hacer non-nullable
    op.alter_column("users", "display_name", nullable=False)

def downgrade():
    op.drop_column("users", "display_name")

JavaScript (Knex.js)

// migración: renombrado seguro de columna usando vistas o dual writes
exports.up = async function(knex) {
  // Fase 1: Agregar nueva columna, mantener columna vieja
  await knex.schema.table("users", (table) => {
    table.string("full_name", 255).nullable();
  });

  // Fase 2: Backfill desde columna vieja
  await knex("users").whereNull("full_name").update({
    full_name: knex.ref("name"),
  });

  // Fase 3: Hacer non-nullable en deploy posterior después de que todo el código escriba la nueva columna
  // await knex.schema.table("users", (table) => { table.string("full_name").notNullable().alter(); });
};

exports.down = async function(knex) {
  await knex.schema.table("users", (table) => {
    table.dropColumn("full_name");
  });
};

Java (Flyway)

// V2__add_user_status.sql
-- Agregar columna enum como text primero, migrar datos, luego agregar CHECK constraint en V3
ALTER TABLE users ADD COLUMN status VARCHAR(20) NULL;

UPDATE users SET status = 'active' WHERE status IS NULL;

-- V3__enforce_user_status.sql (desplegado en siguiente release)
-- ALTER TABLE users ALTER COLUMN status SET NOT NULL;
-- ALTER TABLE users ADD CONSTRAINT chk_status CHECK (status IN ('active', 'inactive', 'banned'));

Explicación

Las migraciones seguras siguen el patrón expand-contract para cualquier cambio breaking:

1. Expand: Agrega el nuevo elemento de esquema (columna, tabla, índice) junto al viejo. Mantenlo opcional.
2. Migrate: Despliega código de aplicación que escriba en ambas estructuras vieja y nueva (dual-write).
3. Contract: Una vez que todos los paths de código viejo desaparecen, haz la nueva estructura requerida y remueve la vieja.

Este patrón garantiza que cualquier instancia en ejecución de tu app (incluyendo durante despliegues rolling) pueda leer y escribir sin errores.

Variantes

Estrategia	Cuándo Usar	Ejemplo
Expand-Contract	Renombrar columnas, cambiar tipos	Agregar full_name, dual-write, eliminar name
Online DDL (pt-online-schema-change)	Tablas MySQL grandes	Alter tablas de 100M+ filas sin locks
Creación de índices concurrente	Índices PostgreSQL	CREATE INDEX CONCURRENTLY para evitar locks de tabla
Backfill por lotes	Migraciones de tablas grandes	Actualizar 10k filas por transacción para evitar locks largos
Despliegue Blue/Green	Sistemas críticos	Ejecutar nuevo esquema en green, cambiar tráfico, luego eliminar viejo

Lo que funciona

• Siempre haz nuevas columnas nullable primero: Las filas existentes no deben fallar durante la migración.
• Backfill antes de hacer non-nullable: Actualiza filas existentes con valores sensatos antes de agregar NOT NULL.
• Agrega índices concurrentemente: En PostgreSQL, usa CREATE INDEX CONCURRENTLY; en MySQL, usa pt-online-schema-change o ALGORITHM=INPLACE.
• Mantén migraciones idempotentes: Ejecutar la misma migración dos veces debería ser seguro.
• Versiona tus migraciones y prueba en copia: Restaura un backup productivo a staging y ejecuta el suite completo de migraciones antes de producción.

Errores Comunes

• Agregar columna non-nullable sin default: Bloquea la tabla mientras puebla cada fila, potencialmente por horas.
• Eliminar columna aún leída por código viejo: Los despliegues rolling ejecutan código viejo y nuevo simultáneamente; el código viejo fallará.
• Ejecutar migraciones pesadas durante tráfico pico: Programa cambios de esquema durante ventanas de mantenimiento o usa herramientas de online DDL.
• Sin plan de rollback: Cada migración debería tener un downgrade probado o script de revert.
• Ignorar timeouts de lock: Las migraciones de larga duración pueden exceder statement timeouts y dejar la base de datos en estado semi-migrado.

Buenas prácticas adicionales

6. Configura lock_timeout antes de DDL. Previene que las migraciones esperen indefinidamente por locks:

SET lock_timeout = '10s';
ALTER TABLE users ADD COLUMN phone VARCHAR(20);

7. Usa statement_timeout para operaciones batch. Aborta backfills que tardan demasiado:

SET statement_timeout = '60s';

8. Ejecuta ANALYZE después de backfills grandes. Actualiza estadísticas del planner para que las consultas elijan planes óptimos:

ANALYZE users;

9. Crea índices concurrentemente. CREATE INDEX CONCURRENTLY en PostgreSQL evita bloquear writes pero no puede ejecutarse dentro de una transacción.

10. Usa feature flags para código dependiente de esquema. Desacopla deploys de código de cambios de esquema:

if feature_flags.is_enabled("use_full_name"):
    display = user.full_name
else:
    display = user.name

Tips de Rendimiento

1. Backfill por lotes con LIMIT y sleep. Procesa 1,000-10,000 filas por lote con pausas cortas para minimizar lag de replicación y contención de locks.

2. Usa CREATE INDEX CONCURRENTLY para todos los índices productivos. Toma más tiempo pero no bloquea writes. Monitorea progreso vía pg_stat_progress_create_index.

3. Configura work_mem para sesiones de migración. Auméntalo para operaciones batch grandes:

SET work_mem = '256MB';

4. Monitorea pg_stat_activity durante migraciones. Observa queries de larga duración y esperas de lock:

SELECT pid, state, wait_event_type, wait_event,
       now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY duration DESC;

5. Usa pg_repack para bloat de tablas. Después de backfills grandes, tablas e índices pueden quedar fragmentados. pg_repack reconstruye tablas sin locks exclusivos.