database-migrations

Patrones de Migración de Base de Datos

Cambios seguros y reversibles en el esquema de base de datos para sistemas de producción.

Cuándo Activar

• Crear o modificar tablas de base de datos
• Agregar/eliminar columnas o índices
• Ejecutar migraciones de datos (relleno, transformación)
• Planificar cambios de esquema sin tiempo de inactividad
• Configurar herramientas de migración para un nuevo proyecto

Principios Fundamentales

1. Cada cambio es una migración — nunca modifiques bases de datos de producción manualmente
2. Las migraciones son solo hacia adelante en producción — los rollbacks usan nuevas migraciones hacia adelante
3. Las migraciones de esquema y datos son separadas — nunca mezcles DDL y DML en una misma migración
4. Prueba las migraciones con datos del tamaño de producción — una migración que funciona con 100 filas puede bloquearse con 10M
5. Las migraciones son inmutables una vez desplegadas — nunca edites una migración que se haya ejecutado en producción

Lista de Verificación de Seguridad de Migración

Antes de aplicar cualquier migración:

• La migración tiene UP y DOWN (o está marcada explícitamente como irreversible)
• Sin bloqueos completos de tabla en tablas grandes (usa operaciones concurrentes)
• Las nuevas columnas tienen valores por defecto o son anulables (nunca agregues NOT NULL sin valor por defecto)
• Índices creados concurrentemente (no en línea con CREATE TABLE para tablas existentes)
• El relleno de datos es una migración separada del cambio de esquema
• Probado contra una copia de los datos de producción
• Plan de reversión documentado

Patrones para PostgreSQL

Agregar una Columna de Forma Segura

-- BIEN: Columna anulable, sin bloqueo
ALTER TABLE users ADD COLUMN avatar_url TEXT;

-- BIEN: Columna con valor por defecto (Postgres 11+ es instantáneo, sin reescritura)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;

-- MAL: NOT NULL sin valor por defecto en tabla existente (requiere reescritura completa)
ALTER TABLE users ADD COLUMN role TEXT NOT NULL;
-- Esto bloquea la tabla y reescribe cada fila

Agregar un Índice Sin Tiempo de Inactividad

-- MAL: Bloquea escrituras en tablas grandes
CREATE INDEX idx_users_email ON users (email);

-- BIEN: No bloqueante, permite escrituras concurrentes
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);

-- Nota: CONCURRENTLY no puede ejecutarse dentro de un bloque de transacción
-- La mayoría de las herramientas de migración necesitan manejo especial para esto

Renombrar una Columna (Tiempo de Inactividad Cero)

Nunca renombres directamente en producción. Usa el patrón expandir-contraer:

-- Paso 1: Agregar nueva columna (migración 001)
ALTER TABLE users ADD COLUMN display_name TEXT;

-- Paso 2: Rellenar datos (migración 002, migración de datos)
UPDATE users SET display_name = username WHERE display_name IS NULL;

-- Paso 3: Actualizar código de aplicación para leer/escribir ambas columnas
-- Desplegar cambios de aplicación

-- Paso 4: Dejar de escribir en la columna antigua, eliminarla (migración 003)
ALTER TABLE users DROP COLUMN username;

Eliminar una Columna de Forma Segura

-- Paso 1: Eliminar todas las referencias de la aplicación a la columna
-- Paso 2: Desplegar aplicación sin la referencia a la columna
-- Paso 3: Eliminar columna en la siguiente migración
ALTER TABLE orders DROP COLUMN legacy_status;

-- Para Django: usa SeparateDatabaseAndState para eliminar del modelo
-- sin generar DROP COLUMN (luego eliminar en la siguiente migración)

Migraciones de Datos Grandes

-- MAL: Actualiza todas las filas en una transacción (bloquea la tabla)
UPDATE users SET normalized_email = LOWER(email);

-- BIEN: Actualización por lotes con progreso
DO $$
DECLARE
  batch_size INT := 10000;
  rows_updated INT;
BEGIN
  LOOP
    UPDATE users
    SET normalized_email = LOWER(email)
    WHERE id IN (
      SELECT id FROM users
      WHERE normalized_email IS NULL
      LIMIT batch_size
      FOR UPDATE SKIP LOCKED
    );
    GET DIAGNOSTICS rows_updated = ROW_COUNT;
    RAISE NOTICE 'Actualizadas % filas', rows_updated;
    EXIT WHEN rows_updated = 0;
    COMMIT;
  END LOOP;
END $$;

Prisma (TypeScript/Node.js)

Flujo de Trabajo

# Crear migración a partir de cambios de esquema
npx prisma migrate dev --name add_user_avatar

# Aplicar migraciones pendientes en producción
npx prisma migrate deploy

# Restablecer base de datos (solo desarrollo)
npx prisma migrate reset

# Generar cliente después de cambios de esquema
npx prisma generate

Ejemplo de Esquema

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  avatarUrl String?  @map("avatar_url")
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")
  orders    Order[]

  @@map("users")
  @@index([email])
}

Migración SQL Personalizada

Para operaciones que Prisma no puede expresar (índices concurrentes, relleno de datos):

# Crear migración vacía, luego editar el SQL manualmente
npx prisma migrate dev --create-only --name add_email_index

-- migrations/20240115_add_email_index/migration.sql
-- Prisma no puede generar CONCURRENTLY, así que lo escribimos manualmente
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users (email);

Drizzle (TypeScript/Node.js)

Flujo de Trabajo

# Generar migración a partir de cambios de esquema
npx drizzle-kit generate

# Aplicar migraciones
npx drizzle-kit migrate

# Enviar esquema directamente (solo desarrollo, sin archivo de migración)
npx drizzle-kit push

Ejemplo de Esquema

import { pgTable, text, timestamp, uuid, boolean } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: uuid("id").primaryKey().defaultRandom(),
  email: text("email").notNull().unique(),
  name: text("name"),
  isActive: boolean("is_active").notNull().default(true),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

Kysely (TypeScript/Node.js)

Flujo de Trabajo (kysely-ctl)

# Inicializar archivo de configuración (kysely.config.ts)
kysely init

# Crear un nuevo archivo de migración
kysely migrate make add_user_avatar

# Aplicar todas las migraciones pendientes
kysely migrate latest

# Revertir la última migración
kysely migrate down

# Mostrar estado de migraciones
kysely migrate list

Archivo de Migración

// migrations/2024_01_15_001_create_user_profile.ts
import { type Kysely, sql } from 'kysely'

// IMPORTANTE: Usa siempre Kysely<any>, no tu interfaz DB tipada.
// Las migraciones están congeladas en el tiempo y no deben depender de los tipos de esquema actuales.
export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('user_profile')
    .addColumn('id', 'serial', (col) => col.primaryKey())
    .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
    .addColumn('avatar_url', 'text')
    .addColumn('created_at', 'timestamp', (col) =>
      col.defaultTo(sql`now()`).notNull()
    )
    .execute()

  await db.schema
    .createIndex('idx_user_profile_avatar')
    .on('user_profile')
    .column('avatar_url')
    .execute()
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable('user_profile').execute()
}

Migrador Programático

import { Migrator, FileMigrationProvider } from 'kysely'
import { promises as fs } from 'fs'
import * as path from 'path'
// Solo ESM — CJS puede usar __dirname directamente
import { fileURLToPath } from 'url'
const migrationFolder = path.join(
  path.dirname(fileURLToPath(import.meta.url)),
  './migrations',
)

// `db` es tu instancia de base de datos Kysely<any>
const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs,
    path,
    migrationFolder,
  }),
  // ADVERTENCIA: Habilita solo en desarrollo. Desactiva la validación de
  // orden por marca de tiempo, lo que puede causar desviación de esquema entre entornos.
  // allowUnorderedMigrations: true,
})

const { error, results } = await migrator.migrateToLatest()

results?.forEach((it) => {
  if (it.status === 'Success') {
    console.log(`migración "${it.migrationName}" ejecutada exitosamente`)
  } else if (it.status === 'Error') {
    console.error(`fallo al ejecutar la migración "${it.migrationName}"`)
  }
})

if (error) {
  console.error('la migración falló', error)
  process.exit(1)
}

Django (Python)

Flujo de Trabajo

# Generar migración a partir de cambios de modelo
python manage.py makemigrations

# Aplicar migraciones
python manage.py migrate

# Mostrar estado de migraciones
python manage.py showmigrations

# Generar migración vacía para SQL personalizado
python manage.py makemigrations --empty app_name -n descripcion

Migración de Datos

from django.db import migrations

def backfill_display_names(apps, schema_editor):
    User = apps.get_model("accounts", "User")
    batch_size = 5000
    users = User.objects.filter(display_name="")
    while users.exists():
        batch = list(users[:batch_size])
        for user in batch:
            user.display_name = user.username
        User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)

def reverse_backfill(apps, schema_editor):
    pass  # Migración de datos, no se necesita reversión

class Migration(migrations.Migration):
    dependencies = [("accounts", "0015_add_display_name")]

    operations = [
        migrations.RunPython(backfill_display_names, reverse_backfill),
    ]

SeparateDatabaseAndState

Eliminar una columna del modelo de Django sin eliminarla de la base de datos inmediatamente:

class Migration(migrations.Migration):
    operations = [
        migrations.SeparateDatabaseAndState(
            state_operations=[
                migrations.RemoveField(model_name="user", name="legacy_field"),
            ],
            database_operations=[],  # No tocar la BD aún
        ),
    ]

golang-migrate (Go)

Flujo de Trabajo

# Crear par de migraciones
migrate create -ext sql -dir migrations -seq add_user_avatar

# Aplicar todas las migraciones pendientes
migrate -path migrations -database "$DATABASE_URL" up

# Revertir la última migración
migrate -path migrations -database "$DATABASE_URL" down 1

# Forzar versión (corregir estado sucio)
migrate -path migrations -database "$DATABASE_URL" force VERSION

Archivos de Migración

-- migrations/000003_add_user_avatar.up.sql
ALTER TABLE users ADD COLUMN avatar_url TEXT;
CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;

-- migrations/000003_add_user_avatar.down.sql
DROP INDEX IF EXISTS idx_users_avatar;
ALTER TABLE users DROP COLUMN IF EXISTS avatar_url;

Estrategia de Migración Sin Tiempo de Inactividad

Para cambios críticos en producción, sigue el patrón expandir-contraer:

Fase 1: EXPANDIR
  - Agregar nueva columna/tabla (anulable o con valor por defecto)
  - Desplegar: la aplicación escribe en AMBAS (antigua y nueva)
  - Rellenar datos existentes

Fase 2: MIGRAR
  - Desplegar: la aplicación LEE de la NUEVA, escribe en AMBAS
  - Verificar consistencia de datos

Fase 3: CONTRAER
  - Desplegar: la aplicación solo usa la NUEVA
  - Eliminar columna/tabla antigua en migración separada

Ejemplo de Cronograma

Día 1: Migración agrega columna new_status (anulable)
Día 1: Desplegar app v2 — escribe tanto en status como en new_status
Día 2: Ejecutar migración de relleno para filas existentes
Día 3: Desplegar app v3 — lee solo de new_status
Día 7: Migración elimina columna antigua status

Antipatrones

Antipatrón	Por Qué Falla	Mejor Enfoque
SQL manual en producción	Sin pista de auditoría, no repetible	Siempre usar archivos de migración
Editar migraciones desplegadas	Causa desviación entre entornos	Crear nueva migración en su lugar
NOT NULL sin valor por defecto	Bloquea tabla, reescribe todas las filas	Agregar anulable, rellenar, luego agregar restricción
Índice en línea en tabla grande	Bloquea escrituras durante la construcción	CREATE INDEX CONCURRENTLY
Esquema + datos en una migración	Difícil de revertir, transacciones largas	Migraciones separadas
Eliminar columna antes de eliminar código	Errores de aplicación por columna faltante	Eliminar código primero, luego eliminar columna en el próximo despliegue