Concepto clave

Las migraciones en Prisma son como el historial de cambios de tu base de datos. Imagina que estás construyendo una casa: primero pones los cimientos (tablas básicas), luego añades paredes (relaciones), y finalmente instalas ventanas (índices). Cada cambio importante se documenta en un plano actualizado. Prisma Migrate automatiza este proceso, generando archivos SQL que transforman tu esquema actual al siguiente estado deseado.

En producción, esto es crucial porque evita drift de esquema (diferencias entre lo que tu código espera y lo que realmente hay en la base de datos). Cada migración es un paso incremental y reversible, permitiendo rollbacks si algo sale mal. No es solo crear tablas; es gestionar la evolución de tu aplicación con control de versiones, similar a usar Git para tu código pero aplicado a la estructura de datos.

Cómo funciona en la práctica

El flujo típico sigue estos pasos:

Modificas tu archivo schema.prisma (por ejemplo, añadiendo un nuevo campo)
Ejecutas npx prisma migrate dev --name add_user_status para generar la migración
Prisma crea una carpeta con un archivo SQL y registra la migración en una tabla especial
En producción, aplicas las migraciones pendientes con npx prisma migrate deploy

Veamos un ejemplo concreto. Supón que tienes un modelo User básico y quieres añadir un campo para rastrear el estado de la cuenta:

// ANTES en schema.prisma
model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
}

Después de la modificación:

// DESPUÉS en schema.prisma
model User {
  id     Int     @id @default(autoincrement())
  email  String  @unique
  name   String?
  status String  @default("active") // Nuevo campo añadido
}

Código en acción

Al ejecutar el comando de migración, Prisma genera un archivo SQL como este:

-- Migration SQL
ALTER TABLE "User" ADD COLUMN "status" TEXT NOT NULL DEFAULT 'active';

Para aplicar esta migración en un entorno de producción, usarías:

# En tu servidor o pipeline de despliegue
npx prisma migrate deploy

# Verificar el estado de las migraciones
npx prisma migrate status

Esto ejecutará solo las migraciones que no se hayan aplicado aún, asegurando que tu base de datos esté sincronizada con el esquema definido.

Errores comunes

Migraciones no verificadas en desarrollo: Aplicar cambios directamente en producción sin probarlos antes. Siempre prueba en un entorno staging idéntico.
Modificar migraciones ya aplicadas: Una vez que una migración se ha ejecutado en producción, no la edites. Crea una nueva migración para revertir o ajustar cambios.
Olvidar backups: Antes de ejecutar migraciones en producción, haz un backup completo de la base de datos. Usa herramientas como pg_dump para PostgreSQL.
Ignorar el tiempo de inactividad: Algunas migraciones (como añadir índices a tablas grandes) pueden bloquear la base de datos. Programa estas operaciones durante ventanas de mantenimiento.
No revisar el SQL generado: Prisma genera SQL automáticamente, pero siempre revisa el archivo generado para asegurarte de que no hay operaciones peligrosas.

Checklist de dominio

Sé generar una migración con prisma migrate dev --name descripcion
Puedo aplicar migraciones en producción usando prisma migrate deploy
Entiendo cómo revertir una migración con prisma migrate resolve --rolled-back nombre_migracion
Verifico el estado de las migraciones con prisma migrate status
Reviso siempre el archivo SQL generado antes de aplicar en producción
Programo migraciones que bloquean tablas grandes para horarios de bajo tráfico
Creo backups de la base de datos antes de cualquier migración en producción

Implementar y desplegar una migración de esquema

En este ejercicio, modificarás un esquema existente y desplegarás los cambios de manera segura.

Clona el repositorio de práctica: git clone https://github.com/example/prisma-migrations-exercise.git
Abre el archivo prisma/schema.prisma y encuentra el modelo Product
Añade un nuevo campo category de tipo String, opcional (nullable)
Genera una migración con el nombre add_product_category usando el comando adecuado
Revisa el archivo SQL generado en la carpeta prisma/migrations
Simula un entorno de producción aplicando la migración con el comando de despliegue
Verifica que la migración se aplicó correctamente consultando la tabla de migraciones

Pistas

Recuerda que los campos opcionales en Prisma se definen con ? después del tipo
El comando para generar migraciones en desarrollo es diferente al de producción
Puedes ver las migraciones aplicadas en la tabla _prisma_migrations

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Generar y Aplicar Migraciones con Prisma Migrate