Saltar al contenido principal
Tutoriales

Prisma migrate deploy en producción: cuándo y dónde ejecutar las migraciones

Las migraciones de Prisma en producción con Docker o Coolify: qué hace migrate deploy, dónde ejecutarlo y cómo cambiar el esquema sin tirar la app.

Israel Palma Sebastià

Este blog es de CREA.MBA, un boilerplate de Next.js con auth, pagos y panel de admin ya montados. Ver qué incluye

En local, las migraciones de Prisma son un comando: prisma migrate dev, y listo. En producción aparecen preguntas que la documentación responde por partes. ¿Se ejecutan en el build o al arrancar? ¿Qué pasa si hay dos contenedores? ¿Y si la migración renombra una columna que la versión anterior de la app sigue leyendo?

Este artículo va de eso, con Prisma 7, PostgreSQL y una app de Next.js desplegada en Docker. Los ejemplos de plataforma son de Coolify porque es lo que usamos, pero el razonamiento vale para Railway, Fly.io o un docker compose a mano.

migrate dev en local, migrate deploy en producción

La documentación de Prisma no deja margen: migrate dev es un comando de desarrollo y nunca se debe usar en producción. Crea migraciones nuevas, usa una base de datos «sombra» y, si detecta que tu base de datos no cuadra con el historial, te propone resetearla.

En producción se usa prisma migrate deploy, que es mucho más modesto:

  • Aplica las migraciones pendientes de prisma/migrations/, en orden.
  • Avisa si alguna migración ya aplicada se ha modificado.
  • No genera migraciones nuevas, no resetea nada y no usa base de datos sombra.
  • No detecta drift: si alguien cambió la base de datos a mano, no se entera.
  • No genera el cliente de Prisma.

Ese último punto se olvida a menudo. El cliente se genera en el build (prisma generate), y las migraciones se aplican contra la base de datos real. Son dos pasos distintos que ocurren en momentos distintos.

Lo previo: las migraciones van en git

Parece obvio, pero lo hemos visto romper un despliegue: un .gitignore heredado de alguna plantilla con prisma/migrations dentro. En local todo funciona porque las migraciones están en tu disco; en el servidor, migrate deploy no encuentra nada que aplicar y la app arranca contra tablas que no existen.

Antes del primer despliegue, revisa el .gitignore:

grep -n -i -E "prisma|migrations" .gitignore

Lo que sí se ignora es el cliente generado (en Prisma 7, la carpeta que pongas en output, típicamente src/generated/), los .env y las bases de datos locales.

Prisma 7: la URL vive en prisma.config.ts

Con Prisma 7 cambian algunas piezas que afectan al despliegue. La URL de conexión sale del bloque datasource del esquema y pasa a prisma.config.ts, y las variables de entorno ya no se cargan solas. Así lo resuelve el boilerplate de CREA.MBA:

// prisma.config.ts
import dotenv from 'dotenv';
import { existsSync } from 'fs';
import { defineConfig, env } from 'prisma/config';

if (existsSync('.env.local')) {
  dotenv.config({ path: '.env.local' });
} else {
  dotenv.config();
}

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: { path: 'prisma/migrations', seed: 'bun prisma/seed.ts' },
  datasource: { url: env('DATABASE_URL') },
});

En el contenedor no hay .env, así que dotenv no carga nada y env('DATABASE_URL') lee la variable que inyecta la plataforma. Otros dos cambios de la versión 7 que conviene tener presentes: migrate dev ya no ejecuta generate por su cuenta y el seed ya no corre automáticamente después de migrate dev o migrate reset.

El build no necesita la base de datos

prisma generate no se conecta a nada: lee el esquema y escribe código. Pero si tu prisma.config.ts exige DATABASE_URL, el build falla en una plataforma que no expone la variable durante la construcción. El boilerplate lo resuelve con un valor de relleno solo para ese paso:

"build": "DATABASE_URL=${DATABASE_URL:-postgresql://placeholder:placeholder@localhost:5432/placeholder} prisma generate && next build"

Lo que no debes hacer es aplicar las migraciones en el build (un RUN prisma migrate deploy en el Dockerfile). La imagen pasaría a depender de que la base de datos de producción sea accesible desde el entorno de construcción, y construir la imagen modificaría producción aunque luego no la despliegues.

Las tres opciones para ejecutarlo

Quedan tres sitios razonables. Cada uno tiene su precio.

1. Al arrancar el contenedor

El comando de arranque aplica las migraciones y luego levanta la app:

bunx prisma migrate deploy && bun start

Es lo más sencillo y funciona bien con una sola instancia. Si la migración falla, la app no arranca; con el healthcheck configurado en Coolify, el despliegue nuevo no pasa la comprobación y la versión anterior sigue sirviendo.

Con varias réplicas, todas intentan migrar a la vez. Prisma lo prevé con un advisory lock en PostgreSQL: solo una ejecuta las migraciones y el resto espera. El tiempo de espera es de 10 segundos y no se puede configurar, según la documentación. Si una migración tarda más (un índice sobre una tabla grande, por ejemplo), las otras réplicas fallan al arrancar y hay que reintentar.

Un detalle de empaquetado: en muchos proyectos prisma (la CLI) está en devDependencies. Si tu imagen de producción instala solo las dependencias de producción, el comando no existirá en el contenedor. O lo mueves a dependencies o ejecutas la migración desde otra imagen.

2. Como paso separado antes de desplegar

Es lo que recomienda Prisma: migrate deploy dentro de un pipeline de CI/CD, contra la base de datos de producción, y solo si termina bien se despliega la versión nueva. En GitHub Actions sería un job previo con la DATABASE_URL como secreto.

El coste es que la base de datos tiene que ser accesible desde donde corra el pipeline. Con un Postgres en tu VPS sin puerto público (lo normal en Coolify), eso significa abrir un túnel o un puerto, y no siempre compensa.

3. Los comandos de pre y post despliegue de Coolify

Coolify tiene dos campos para esto, y su documentación explica una diferencia que cambia la elección:

  • El comando de pre-despliegue corre en el contenedor actual, antes de sustituirlo. Es decir, con el código y la carpeta prisma/migrations de la versión anterior. Las migraciones nuevas todavía no están ahí. Además, en el primer despliegue no hay contenedor actual y Coolify se lo salta.
  • El comando de post-despliegue corre en el contenedor nuevo, pero cuando el despliegue ya se ha dado por completado. Si falla, queda en el log y el despliegue sigue marcado como correcto.

Para migrate deploy ninguno de los dos encaja del todo. El pre-despliegue no ve las migraciones nuevas, y el post-despliegue deja la app nueva sirviendo durante unos segundos contra el esquema viejo, sin frenar nada si la migración falla. Por eso, en un servidor con una sola instancia, nosotros preferimos la opción 1.

Cambiar el esquema sin tirar la app

Elijas la opción que elijas, hay un momento en que la versión vieja de la app y el esquema nuevo conviven (o al revés). Con una migración que solo añade una tabla o una columna opcional, da igual. Con una que borra o renombra, no.

Prisma, por ejemplo, genera un renombrado de columna como DROP + ADD si no lo editas a mano, con lo que pierdes los datos. Y aunque escribas un RENAME COLUMN, la instancia anterior sigue buscando el nombre viejo hasta que la sustituyen.

El patrón que evita sustos se llama expand and contract: los cambios destructivos se reparten en varios despliegues.

  1. Ampliar. Añade la columna nueva, opcional o con valor por defecto. La app escribe en las dos y lee de la vieja.
  2. Migrar datos. Copia lo existente a la columna nueva, con un script o en la propia migración SQL.
  3. Cambiar lecturas. La app lee de la nueva.
  4. Contraer. En un despliegue posterior, borra la columna vieja.

Para un SaaS con pocos usuarios puede sonar a ceremonia. Pero basta una vez con un NOT NULL añadido a una tabla con filas para que la migración falle en producción a medio despliegue, y entonces apetece haberlo hecho en dos pasos.

Antes de cada despliegue con migraciones, lee el SQL que generó Prisma en prisma/migrations/_/migration.sql. Es la única forma de ver si un cambio aparentemente inocente del esquema se ha convertido en un DROP.

Cuando una migración falla a medias

Si migrate deploy falla, Prisma marca la migración como fallida en la tabla _prisma_migrations y no aplica ninguna más hasta que lo resuelvas. Los pasos:

  1. Mira el error y el estado real de la base de datos: qué partes de la migración llegaron a aplicarse.
  2. Corrige a mano lo que haga falta (deshacer lo aplicado o completarlo).
  3. Marca la migración con prisma migrate resolve --rolled-back si la vas a repetir, o --applied si la completaste a mano.
  4. Vuelve a ejecutar migrate deploy.

Para llegar aquí con tranquilidad, haz una copia de la base de datos antes de cada despliegue con migraciones destructivas. En Coolify, los backups programados de Postgres se activan desde los ajustes del recurso y se pueden lanzar a mano antes de desplegar.

El seed, lejos de producción

Una tentación al montar un entorno nuevo es lanzar el seed para tener datos. Revisa antes qué hace: los seeds de demo suelen empezar con deleteMany() para dejar la base de datos limpia, y el de muchos starters (el de CREA.MBA incluido) es así. Contra una base de datos de producción, eso es borrarlo todo.

Para datos que necesites en producción (planes, categorías, un usuario administrador), escribe un script aparte e idempotente, con upsert, que puedas ejecutar dos veces sin consecuencias.

Lo que te llevas

  • migrate dev en local; migrate deploy en producción, siempre.
  • Las migraciones van en git. El cliente generado, no.
  • El build genera el cliente; las migraciones se aplican fuera del build.
  • Con una instancia, migrar al arrancar es lo más simple. Con varias, mira el advisory lock y sus 10 segundos.
  • En Coolify, el pre-despliegue corre con el código viejo: no te sirve para migraciones nuevas.
  • Los cambios destructivos, en varios despliegues.

Si estás montando el servidor, la parte de infraestructura la contamos en Hetzner + Coolify como alternativa a Vercel, y por qué elegimos este ORM en Prisma + PostgreSQL para SaaS. CREA.MBA trae Prisma 7 configurado con prisma.config.ts, el adaptador de PostgreSQL y el build preparado para no necesitar la base de datos.

¿Dónde ejecutas tú las migraciones: al arrancar, en el pipeline o a mano por SSH?

Next.jsPrismaPostgreSQLCoolifyDeploy

¿Te gustó este artículo?

Suscríbete para más tutoriales y tips sobre crear productos con IA