Establecer una línea de base para una base de datos existente en Prisma sin ejecutar migrate reset

Point Prisma Migrate se ejecuta en una base de datos que ya contiene tablas y datos, y es muy probable que la primera ejecución de npx prisma migrate dev se detenga con una advertencia de desviación y ofrezca restablecer todo. Esa notificación indica que la base de datos tiene una estructura sobre la cual el historial de migraciones de Prisma no tiene conocimiento. Al aceptarla, se borrarán tus datos. Esta guía explica por qué ocurre el conflicto, por qué restablecer casi nunca es la solución adecuada para una base de datos importante, y cómo establecer como punto de referencia el esquema existente para que Prisma lo considere como punto de partida y aplique los cambios únicamente a partir de allí.

Por qué Prisma detecta un conflicto

Prisma Migrate mantiene dos registros de la evolución de tu esquema: los archivos de migración en prisma/migrations y una tabla llamada _prisma_migrations dentro de la base de datos que indica cuáles de esos archivos han sido aplicados. Cuando ejecutas migrate dev, Prisma reproduce el historial de migraciones en una base de datos temporal y compara el resultado con la real.

Si la base de datos real ya contiene tablas que ninguna migración creó, por ejemplo porque fue creada a mano, con otra herramienta o con una versión anterior de la aplicación, las dos no coinciden. Prisma denomina a esto desviación. Dado que migrate dev es una orden de desarrollo, su solución por defecto es borrar la base de datos y reconstruirla a partir del historial de migraciones, por lo que propone un restablecimiento. Esto es razonable para una base de datos local temporal, pero destructivo para cualquier otro caso.

Si desea más información sobre cómo participa la base de datos shadow en esta comparación, consulte La base de datos shadow de Prisma y las incoherencias en los nombres.

Por qué migrate reset es la solución incorrecta

npx prisma migrate reset elimina la base de datos, o cada tabla de su esquema, la recrea a partir de sus migraciones y ejecuta los scripts de inicialización. Todas las filas existentes se pierden. En una base de datos con usuarios reales, pedidos o contenido, eso no es resolución de conflictos sino pérdida de datos.

El enfoque mejor es dejar la base de datos intacta y, en su lugar, actualizar la visión que tiene Prisma del mundo con ella. Para ello, registre la estructura actual como una primera migración e indique a Prisma que esta migración ya está implementada.

Paso a paso para establecer la línea de referencia

Paso 1: Analizar la base de datos existente

Ejecuta npx prisma db pull. Prisma se conecta a la base de datos, lee sus tablas, columnas, índices y relaciones, y escribe los modelos correspondientes en schema.prisma. Después de este paso, el archivo de esquema describe la base de datos tal como está.

Paso 2: Generar una migración de referencia sin aplicarla

Cree una carpeta para la línea de referencia, por ejemplo prisma/migrations/0_init. El prefijo 0_ hace que se ordene antes que cualquier otra migración con fecha. Luego genere el SQL necesario para crear el esquema actual a partir de cero y guárdelo allí, utilizando npx prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script > prisma/migrations/0_init/migration.sql. En las versiones recientes de Prisma, el parámetro de destino puede llamarse --to-schema en su lugar, así que consulte npx prisma migrate diff --help según su versión.

Este paso es importante porque genera el archivo de migración sin modificar la base de datos. Un error común es ejecutar npx prisma migrate dev --name baseline en este momento. En una base de datos que ya cuenta con tablas y no tiene historial de migraciones, esa orden detecta la misma desviación que antes y solicita volver a restablecerla, lo cual es exactamente lo que se intenta evitar. La consulta SQL de línea base nunca debe ejecutarse sobre la base de datos existente, ya que sus tablas ya están presentes.

Paso 3: Marcar la línea base como aplicada

Ejecuta npx prisma migrate resolve --applied 0_init. El argumento es el nombre de la carpeta de migraciones. Si se creó una carpeta con una marca de tiempo, como 20250101120000_baseline, debes indicar ese nombre completo, y no solo baseline.

_prisma_migrations indicando que se ha aplicado la línea de base. En efecto, estás modificando los registros contables de Prisma para que acepte la estructura actual como intencional y válida.

Cómo resuelve este conflicto

Se asemeja a un conflicto de fusión en Git: cuando tu rama carece de commits ya presentes en main, actualizas la rama en lugar de eliminar main. Aquí, la base de datos está más avanzada, y actualizas el historial de Prisma para que se alinee con ella.

Después de registrar la línea de base, el siguiente comando npx prisma migrate dev vuelve a ejecutar 0_init en la base de datos de sombra, obtiene la misma estructura que la base de datos real y no detecta ninguna discrepancia. A partir de entonces, cuando modifiques schema.prisma, Prisma generará una nueva migración que contenga únicamente las diferencias y aplicará solo esas modificaciones.

Por qué esto es importante para las bases de datos grandes

El establecimiento de una línea base rinde más beneficios cuando la base de datos alberga grandes cantidades de datos. Con la línea base registrada en _prisma_migrations y el esquema que coincide con la base de datos en uso, Prisma deja intactas las tablas y filas existentes y aplica únicamente los cambios nuevos, de modo que su tabla users permanece sin alteraciones.

Tenga en cuenta estos puntos prácticos:

• Ejecute migrate resolve --applied una vez en cada entorno existente, como staging y producción, ya que cada base de datos tiene su propia tabla _prisma_migrations.
• En producción, aplique las migraciones posteriores con npx prisma migrate deploy, no con migrate dev, que está destinado únicamente al desarrollo.
• Guarde la carpeta de línea base en control de versiones para que todos los desarrolladores y tareas de CI compartan el mismo punto de partida.

Puntos clave

• Una advertencia de desviación en una base de datos existente significa que falta el historial de migraciones de Prisma, no que la base de datos esté incorrecta.
• Restablecer elimina los datos; úselo solo como herramienta para bases de datos locales temporales.
• Establezca la línea base inspeccionando con db pull, generando SQL con migrate diff --from-empty y registrándolo con migrate resolve --applied.
• No use migrate dev para crear la línea base a partir de una base de datos ya poblada, ya que activa el mismo mensaje de restablecimiento.
• Después de establecer la línea base, Prisma gestiona únicamente cambios incrementales, y los datos existentes permanecen intactos.

Lecturas relacionadas

• La base de datos sombra de Prisma y la diferencia en el nombramiento: un manual de operación — Por qué prisma migrate dev solicita restablecer la base de datos, cómo configurar una base de datos sombra segura y cómo mapear la convención de mayúsculas/minúsculas de Prisma al formato snake_case de Postgres.
• Drizzle o Prisma? Verifique el tipo de unión y el SQL registrado antes de elegir — Modelice las mismas tablas de usuarios y facturas en Drizzle y Prisma, compare los tipos de resultados de las uniones y el SQL registrado, y detecte las asignaciones del controlador que convierten totales en cadenas de texto.