Revertir y Gestionar Historial de Migraciones

Concepto clave

Revertir y gestionar el historial de migraciones en Prisma es como tener un sistema de control de versiones para tu base de datos. Imagina que estás construyendo una casa: cada migración es un cambio estructural (añadir una habitación, modificar una pared). Si descubres que el último cambio tiene problemas, necesitas poder deshacerlo de forma segura sin dañar lo que ya funciona.

En producción, esto es crítico porque los errores en migraciones pueden causar downtime o pérdida de datos. Prisma maneja esto a través de comandos específicos que interactúan con la tabla _prisma_migrations, que actúa como el libro de registro de todos los cambios aplicados. No es solo revertir, sino entender qué migraciones se han aplicado, cuándo y por qué.

Cómo funciona en la práctica

El flujo típico para revertir una migración implica estos pasos:

1. Verificar el estado actual de migraciones con prisma migrate status.
2. Identificar la migración problemática (generalmente la última aplicada).
3. Usar prisma migrate resolve para marcar migraciones como revertidas o aplicadas manualmente.
4. En casos simples, crear una nueva migración que deshaga los cambios.

Ejemplo: Si añadiste una columna emailVerified a la tabla User y causa errores en producción, necesitas revertir ese cambio. Primero revisas el historial, luego creas una migración que elimine esa columna, aplicándola de forma controlada.

Código en acción

Antes: Schema con columna problemática

model User {
  id        Int     @id @default(autoincrement())
  email     String  @unique
  name      String?
  // Columna añadida en migración reciente
  emailVerified Boolean @default(false)
}

Después: Revertir creando nueva migración

# 1. Ver estado actual
npx prisma migrate status

# 2. Crear migración para revertir el cambio
npx prisma migrate dev --name remove_email_verified

# 3. En el archivo de migración generado, escribir SQL para revertir
-- En el archivo SQL de la migración
ALTER TABLE "User" DROP COLUMN "emailVerified";

Errores comunes

• Revertir migraciones ya aplicadas en producción sin backup: Siempre haz backup de la base de datos antes de revertir en producción.
• Confiar solo en prisma migrate reset: Este comando borra toda la base de datos, no es para producción. Usa prisma migrate resolve para gestionar migraciones específicas.
• No probar reversiones en staging: Siempre prueba la reversión en un entorno idéntico a producción antes de aplicarla.
• Olvidar dependencias de datos: Si eliminas una columna, asegúrate de que ningún código o query dependa de ella.
• Ignorar el historial: Revisa _prisma_migrations regularmente para entender el estado de la base de datos.

Checklist de dominio

1. Sé ejecutar prisma migrate status e interpretar su salida correctamente.
2. Puedo revertir una migración reciente creando una nueva migración con los cambios inversos.
3. Entiendo cómo usar prisma migrate resolve para marcar migraciones como aplicadas o revertidas manualmente.
4. Conozco la diferencia entre migrate reset (dev) y migrate resolve (producción).
5. Antes de revertir en producción, siempre hago backup de la base de datos.
6. Verifico que el código de la aplicación no dependa de los cambios que voy a revertir.
7. Documento cada reversión en el historial de cambios del proyecto.

Revertir una migración problemática en un proyecto existente

En este ejercicio, trabajarás con un proyecto Prisma que tiene una migración reciente que causó problemas. Tu tarea es revertirla de forma segura.

1. Clona el repositorio de ejemplo: git clone https://github.com/example/prisma-migration-revert-exercise
2. Instala dependencias: npm install
3. Examina el schema actual en prisma/schema.prisma. Notarás que hay un modelo Product con una columna price de tipo Float.
4. Ejecuta npx prisma migrate status para ver las migraciones aplicadas.
5. La última migración (llamada "add_product_price") cambió price de Int a Float, pero esto rompió una API existente.
6. Crea una nueva migración para revertir este cambio, volviendo price a tipo Int.
7. Aplica la migración y verifica que la base de datos refleje el cambio.
8. Ejecuta npx prisma studio para confirmar que la tabla Product tiene price como entero.

• Usa npx prisma migrate dev --name revert_price_change para crear la migración.
• En el archivo SQL generado, escribe ALTER TABLE \"Product\" ALTER COLUMN \"price\" TYPE INTEGER USING \"price\"::integer; para cambiar el tipo.
• Recuerda que USING es necesario en PostgreSQL para conversiones de tipo.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.