Prisma en producción: revisa las migraciones antes de cambiar una base con datos

Una aplicación creada con IA puede funcionar con una base local y fallar al publicarla. Crear tablas en otro servidor, trasladar los registros y cambiar el esquema de una base que ya tiene datos son tres operaciones distintas. Una migración de Prisma no copia automáticamente las filas de tu ordenador a producción.

Esta guía está preparada para Prisma 7.10.0, con la versión fijada en el proyecto. La documentación actual también describe comandos de Prisma 8: comprueba la versión instalada antes de copiar una receta. El ensayo local descrito abajo ha terminado; no demuestra integración nativa en Hostbrid.

Primero identifica qué base vas a cambiar

Si el destino está vacío y tienes un historial de migraciones revisado, puedes aplicar ese historial al destino. Si ya hay tablas o datos, revisa cómo se creó el esquema y si Prisma tiene una historia que coincida con él. El error P3005, «database schema is not empty», no se resuelve borrando una base que necesitas conservar.

Una base existente puede requerir un baseline: una migración inicial que representa el esquema existente y se registra como aplicada tras verificar esa correspondencia. No marques cualquier archivo como aplicado para ocultar un error. Una marca incorrecta deja el historial y el esquema real en estados distintos y puede trasladar el problema a la siguiente entrega.

Si además quieres llevar datos desde tu equipo, prepara una operación de exportación e importación aparte, con versiones compatibles y un destino adecuado. Verifica quién seguirá escribiendo mientras haces el traslado. Una captura de pantalla con tablas creadas no prueba que hayan llegado todas las filas, relaciones o secuencias.

No uses el comando de desarrollo como entrega de producción

En Prisma 7, migrate dev genera y aplica migraciones en desarrollo; puede detectar diferencias que requieran reset. migrate reset elimina los datos. migrate deploy aplica las migraciones pendientes que ya existen: no genera por ti una migración nueva ni el cliente y tampoco verifica todas las diferencias del esquema.

Esto no hace que migrate deploy sea una garantía de conservación. Si el archivo SQL contiene un DROP TABLE, una columna eliminada o una transformación equivocada, aplicar ese archivo puede destruir información. Revisa el cambio de SQL y no solo el mensaje final del comando. Fijar la versión y conservar el lockfile hace el ensayo reproducible; no convierte en correcto cualquier cambio.

Ensaya el cambio con registros que permitan detectar una pérdida

Trabaja sobre una base desechable que controles. Incluye registros con identificadores conocidos, relaciones y valores que deban sobrevivir. Antes y después, compara esos valores, no solo el número de filas. Dos tablas pueden tener el mismo recuento y contener datos distintos.

Un campo obligatorio nuevo necesita una estrategia para las filas existentes. Puedes introducirlo como nullable, completar los valores mediante una transformación explícita y después imponer la restricción cuando hayas verificado que no quedan nulos. También debes comprobar las restricciones únicas y las claves foráneas que necesita la aplicación.

Vuelve a aplicar el historial al mismo destino para comprobar qué queda pendiente. Ese resultado no sustituye la revisión del SQL, el ensayo de recuperación o la compatibilidad de la versión anterior y la nueva de tu aplicación. Una copia que nunca has restaurado no demuestra que puedas recuperar el servicio.

Decide desde dónde podrá ejecutarse la migración

Una DATABASE_URL contiene acceso privado; no la incluyas en variables públicas como VITE_, en el repositorio ni en ejemplos que compartas. El proceso que ejecuta la migración necesita alcanzar la base y disponer de permisos adecuados para los cambios aprobados. La aplicación en funcionamiento puede necesitar permisos diferentes.

Hostbrid ofrece bases relacionales y describe una red privada por defecto en su página de bases de datos. Comprueba cómo llegará a esa red el proceso de migración antes de contratar o conectar un CI externo. Esta guía no demuestra acceso desde cualquier proveedor de CI ni una configuración automática de Prisma. Consulta los planes vigentes y confirma el motor y la conectividad que necesita tu aplicación.

Si aún no sabes qué parte de tu proyecto necesita servidor, empieza por elegir el alojamiento de una web creada con IA. Publicar el frontend y mantener una base de producción son decisiones relacionadas que requieren verificaciones propias.

Qué comprobamos en el ejemplo original

El 8 de octubre ensayamos 12 casos con Prisma 7.10.0, Node 22.23.3, npm 10.9.9 y PostgreSQL 16.13 Homebrew en macOS ARM64. El clúster era nuevo y local, con dos cuentas y dos entradas ficticias. No conectamos una base de Hostbrid ni de un cliente.

La migración aditiva conservó cada campo original, ID y relación; el backfill produjo los nombres esperados. Las restricciones rechazaron duplicados y referencias inválidas. La rama de base existente reprodujo P3005 antes del baseline; un baseline correcto y un diff sin diferencias permitieron aplicar la aditiva. Con un baseline incorrecto, resolve terminó con éxito, pero el diff detectó las restricciones ausentes y el ensayo no avanzó.

Restauramos el dump en tres bases nuevas y comparamos los datos. En otra copia, un DROP COLUMN terminó con éxito y eliminó valores: conservar el número de filas no bastó. Añadir una columna obligatoria sin completar las filas falló; el siguiente deploy quedó bloqueado. Los resultados negativos eran esperados y solo afectaron a datos sintéticos.

El servidor se detuvo y comprobamos su parada. Esto no prueba tablas grandes, concurrencia, tiempos de bloqueo, PITR, backups de proveedor ni ejecución de migraciones dentro de Projects.

Prisma 7 migrate deploy · Prisma 7 baselining

Ejecuta el ensayo en un entorno desechable

El ejemplo original MIT está fijado a la revisión 87a2a843867be8b6244a68fbc50b3919f4d2b82e. Necesita macOS ARM64, Node 22.23.3, npm 10.9.9, PostgreSQL 16.13 Homebrew instalado y el puerto local 55439 libre. PG_BIN permite indicar el directorio de binarios. No adaptes estos contraejemplos para ejecutarlos sobre una base real: el runner crea y detiene su propio clúster e ignora una DATABASE_URL recibida.

git clone https://github.com/ocentelles/hostbrid-example-prisma-migrations.git
cd hostbrid-example-prisma-migrations
git checkout --detach 87a2a843867be8b6244a68fbc50b3919f4d2b82e
node --version
npm --version
npm ci --ignore-scripts --no-audit --no-fund
npm run essay