Cómo integrar Next.js con Prisma y PostgreSQL

Aprende a integrar Next.js con Prisma y PostgreSQL en esta guía completa paso a paso. Configuración, migraciones y APIs listas para producción

oscar Escrito por oscar 17 March 2025 1 0
NextJS

En el desarrollo web moderno, la combinación de Next.js, Prisma y PostgreSQL se ha convertido en una de las más populares para crear aplicaciones full-stack eficientes, rápidas y escalables. Next.js ofrece un entorno React con SSR y generación estática; Prisma es un ORM moderno y altamente tipado que facilita el manejo de la base de datos; y PostgreSQL es una base de datos relacional robusta, ideal para proyectos de cualquier tamaño.

En esta guía te enseñaré paso a paso cómo crear un proyecto con Next.js, Prisma y PostgreSQL, desde la configuración inicial hasta la creación de una API funcional.

Antes de iniciar recomiendo leer

Crear el proyecto Next.js

Comienza creando tu aplicación Next.js con soporte para TypeScript:

npx create-next-app@latest next-prisma --typescript

Esto generará la estructura básica de Next.js con TypeScript.

cd next-prisma

Instalar Prisma y PostgreSQL

Instalar y configurar PostgreSQL

Nota: Para este paso ya debe tener el motor de base de datos postgres instalado, si aun no lo tiene puede sergir estos pasos en los siguientes post

Trabajar con la consola

Consola de postgresql

Instalar el ORM en nextjs

Instala Prisma ORM y el cliente de PostgreSQL:

npm install prisma --save-dev
npm install @prisma/client
npm install pg

Inicializar Prisma

npx prisma init

Prisma configura el entorno inicial de tu proyecto para que puedas trabajar con bases de datos relacionales de manera sencilla y segura.

Lo que primero hace es crea la carpeta ´/prisma´ y dentro de prisma crear un archivo llamado schema.prisma 

/prisma
  └── schema.prisma

Luego crea o modifica el archivo .env en la raíz de tu proyecto, este archivo es donde colocas tu cadena de conexión a la base de datos de forma segura:

DATABASE_URL="postgresql://usuario:password@localhost:5432/mi_base_de_datos"

Definir modelos en Prisma

Define tus modelos en prisma/schema.prisma.

Para mas información, podemos ver la documentación oficial en https://www.prisma.io/docs/orm/prisma-schema/data-model/models ademas si desea saber de las relaciones esta https://www.prisma.io/docs/orm/prisma-schema/data-model/relations

Por ejemplo, un modelo básico de post para un blog:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Post {
  id        String   @id @default(uuid())
  title     String
  content   String
  published Boolean  @default(false)
  createdAt DateTime @default(now())
}

Migraciones 

Crear primera migración

Para entender las migraciones nos guiaremos de https://www.prisma.io/docs/orm/prisma-migrate/getting-started en donde explica a detalle el tema, a continuación, procedemos a crear la migración para el modelo post.

Creamos la migración inicial 

npx prisma migrate dev --name init

Respuesta

Loaded Prisma config from prisma.config.ts.

Prisma config detected, skipping environment variable loading.
Prisma schema loaded from prisma\schema.prisma
Datasource "db": PostgreSQL database "oscar", schema "public" at "localhost:5432"

Already in sync, no schema change or pending migration was found.

✔ Generated Prisma Client (6.19.0) to .\src\generated\prisma in 43ms

Esto creará el siguiente esquema:

prisma\migrations/
  └─ 20251106154132_init/
    └─ migration.sql

Adicionar campos al esquema

Si necesitamos modificar los modelos, podemos crear mas modificaciones y si respectiva migración, procedemos a modificar:

model User {
  ...
  jobTitle  String?
  ...
}

Al modelo User agregamos el campo jobTitle, luego creamos una nueva migración:

npx prisma migrate dev --name added_job_title

Respuesta

prisma\migrations/
  └─ 20251106170455_added_job_title/
    └─ migration.sql

Verificar la migración

Prisma y el cliente de prisma posee una studio web que permite ver la base de datos creada, esta la podemos usar con:

npx prisma studio

Mas información en https://www.prisma.io/docs/orm/tools/prisma-studio

Nota: podemos usar otros entrono como DBeaver para ver la base de datos y las tablas.

Generar base de datos

npx prisma generate

Crear cliente Prisma para Next.js

Cuando instalas Prisma y ejecutas: npx prisma generate Prisma crea una clase PrismaClient que te permite interactuar con tu base de datos desde el código JavaScript o TypeScript.

Este objeto prisma es tu puente directo a la base de datos.

⚠️ El problema con Next.js (modo desarrollo)

Next.js en modo dev:

  • Recarga el servidor automáticamente cada vez que cambias un archivo.
  • Esto hace que tu código se vuelva a ejecutar muchas veces.

Si cada vez que recarga creas un nuevo new PrismaClient(), tendrás:

  • Varias conexiones abiertas a la base de datos.
  • Un error como:

✅ La solución: crear un cliente Prisma global, 📄 Archivo: lib/prisma.ts

import { PrismaClient } from "@prisma/client";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma =
  globalForPrisma.prisma ||
  new PrismaClient({
    log: ["query"],
  });

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

🧩 ¿Qué hace esto?

  • Crea una única instancia global de PrismaClient.
  • La reutiliza en cada recarga de Next.js.
  • Evita fugas de memoria y conexiones duplicadas.

Usar Prisma en un endpoint (Next.js App Router)

Ejemplo: app/api/users/route.ts

import { prisma } from "@/lib/prisma";
import { NextResponse } from "next/server";

export async function GET() {
  const users = await prisma.user.findMany();
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const data = await request.json();
  const user = await prisma.user.create({
    data
  });

  return NextResponse.json(user);
}

Ejecutar proyecto

npm run dev

Abre: http://localhost:3000/api/users

Respuesta: [{"id":1,"name":"Oscar","email":"oscar@test.com","createdAt":"2025-11-06T11:56:57.375Z"}]

Comentario

Debe aceptar antes de enviar