Arrancar una API de NestJS y Prisma sin errores de relación ni P1001

Casi todas las funcionalidades de backend que un equipo desarrolla posteriormente, desde la autenticación hasta el modelo multiinquilino y el control de acceso basado en roles, se construyen sobre las primeras horas de configuración del proyecto. Si las variables de entorno, la conexión a la base de datos, las relaciones entre esquemas y las migraciones se configuran de forma descuidada al inicio, cada solicitud posterior hereda ese desorden. Esta guía explica cómo configurar una API NestJS respaldada por Prisma y PostgreSQL, detalla los tres problemas que con más frecuencia impiden alcanzar ese primer hito y ofrece una lista de verificación para saber cuándo realmente está listo el cimiento del proyecto.

Así es un bootstrap completado

Es útil definir el objetivo antes de tocar la CLI. Un bootstrap se considera completo cuando un revisor puede clonar la rama y confirmar lo siguiente:

• Una aplicación NestJS escrita en TypeScript que se inicia sin errores

Prisma conectado a una base de datos PostgreSQL

Configuración cargada desde variables de entorno en lugar de valores codificados directamente

Un conjunto inicial de modelos de datos que reflejan el dominio

Una migración que se aplica sin problemas a una base de datos vacía

Una solicitud de integración bien definida que el resto del equipo puede revisar y fusionar

Las restricciones son deliberadamente estrictas: NestJS y Prisma como único framework y ORM, PostgreSQL como base de datos, además de las convenciones existentes del equipo para la configuración y Git.

El conjunto de herramientas

• Framework y lenguaje: NestJS con TypeScript
• Acceso a datos: prisma (la CLI) y @prisma/client (el cliente de consultas generado)
• Configuración: @nestjs/config
• Base de datos: una instancia local de PostgreSQL
• Verificación: la CLI de Prisma, además de un navegador o cliente API para acceder a los endpoints

Configuración del esqueleto del proyecto

Comience generando una aplicación nueva con la CLI de Nest, luego agregue Prisma e inicialícelo dentro del proyecto. La inicialización crea un directorio prisma/ para el esquema y las migraciones, mientras que el código de la aplicación permanece en src/.

A continuación, cree un archivo .env que contenga DATABASE_URL, la cadena de conexión a PostgreSQL que lee Prisma. Cargue la configuración a través del módulo @nestjs/config para que la aplicación obtenga los valores del entorno en lugar de de literales dispersos por el código. Asegúrese de que .env esté incluido en .gitignore; subir credenciales reales en la primera PR es un error fácil de cometer y difícil de corregir.

Antes de escribir cualquier modelo, confirme que Prisma pueda acceder realmente a la base de datos. Si desea un análisis más detallado del lado de Prisma por separado, consulte cómo configurar Prisma 7 con PostgreSQL en un proyecto TypeScript Node.js, y revise la documentación actual de Prisma para obtener detalles específicos de cada versión.

Modelado de las primeras entidades

Para un producto multiinquilino, un esquema de inicio razonable consta de cuatro modelos:

• Tenant, que representa a una organización que utiliza el sistema
• User, que representa a una persona que inicia sesión
• Role, para la asignación básica de roles dentro de un inquilino
• Invite, para incorporar nuevos usuarios a un inquilino

Juntos, estos elementos definen de qué dependen las funcionalidades posteriores: los usuarios pertenecen a arrendatarios, ocupan roles y llegan a través de invitaciones. Cada relación requiere un campo en ambos lados, lo cual es la causa del primer error que se muestra a continuación.

Una vez que el esquema sea validado, ejecute la migración inicial para que la estructura de la base de datos coincida con el esquema. Manténgala libre de experimentos, ya que cada miembro del equipo la aplicará localmente.

Agregar un punto de extremo de salud

En el lado de la API, agregue un único controlador que exponga /health y devuelva simplemente OK. Puede parecer algo sencillo, pero cumple una función importante: le brinda a usted, a su pipeline de CI y, eventualmente, a su balanceador de carga o orquestador, una forma económica de verificar si el proceso está activo y atendiendo solicitudes.

Tres errores que suelen bloquear el primer hito

Prisma rechaza una relación sin un campo opuesto

Síntoma: la validación del esquema falla, indicando que una relación carece de su campo opuesto.

Causa: Prisma exige que las relaciones se declaren en ambos modelos. Si User hace referencia a Tenant pero Tenant no tiene un campo que enumere a sus usuarios, desde el punto de vista de Prisma el esquema está incompleto.

Solución: agregue los campos de referencia faltantes en los modelos relacionados y luego ejecute prisma format. El formateador normaliza el archivo y puede completar los campos de relación que faltan, por lo que es buena práctica ejecutarlo después de cada modificación del esquema.

P1001: no se puede llegar al servidor de base de datos

Síntoma: Prisma muestra el código de error P1001 y no puede conectarse a PostgreSQL.

Causa: por lo general, una de dos cosas. O bien el servidor PostgreSQL no está en ejecución, o bien el puerto indicado en DATABASE_URL no coincide con el puerto en el que escucha el servidor.

Solución: confirme que el proceso de la base de datos se está ejecutando localmente, y luego compare el host y el puerto de la cadena de conexión con la configuración real del servidor.

Una solicitud de pull que parece borrar todo

Síntoma: un revisor abre la solicitud de pull y observa que todos los archivos del repositorio han sido eliminados.

Causa: el commit se realizó desde un estado de Git incorrecto, por lo que la diferencia se compara con algo muy distinto a lo que se pretendía.

Solución: en lugar de intentar reparar la historia complicada, cree una rama nueva a partir de la base correcta y aplique únicamente los cambios previstos. Ejecutar git status y revisar git diff en comparación con la rama objetivo antes de hacer el push permite detectar este tipo de errores temprano.

Verificación de la configuración

La verificación debe ser algo repetible sin complicaciones:

• Ejecute npx prisma migrate dev y confirme que la migración se aplica sin errores
• Inicie el servidor NestJS
• Abra /health en un navegador o cliente API y verifique si hay una respuesta OK

Cuando la migración se complete sin problemas y el endpoint de estado responda, las bases están listas para la siguiente funcionalidad.

Puntos clave

• Trate el código de inicialización como un producto con criterios de aceptación claros, y no como una estructura temporal.

Declare cada relación Prisma en ambos lados y deje que prisma format mantenga el esquema ordenado.

Cuando vea P1001, verifique que PostgreSQL esté en ejecución y que el puerto en DATABASE_URL sea correcto antes de intentar depurar cualquier otra cosa.

Un endpoint de estado solo lleva unos minutos de implementación, pero aporta beneficios en las pruebas de integración continua, monitoreo e implementación.

Las solicitudes de pull pequeñas y bien enfocadas, con un historial limpio, forman parte del trabajo de ingeniería, no son algo que se hace después.

Lecturas relacionadas

• Desplegando NestJS en Bun y Prisma 7 en Cloud Run sin los errores de construcción — Un pipeline funcional de GitHub Actions para enviar una aplicación NestJS en Bun con Prisma 7 y Neon a Cloud Run, además de las soluciones para Docker y conexiones que suelen causar problemas a los equipos.
• MovieVault Walkthrough: Una API de lista de reproducción con Express 5, Prisma 7 y JWT — Una especificación de ejercicio full-stack con tiempo limitado y su backend basado en Express, Prisma y JWT, con notas de revisión sobre verificaciones de propiedad, efectos en cadena y manejo de errores.