Configuración de Prisma 7 en un proyecto Next.js 16 con TypeScript
Aprenda cómo instalar, configurar y migrar Prisma 7 con PostgreSQL en una aplicación Next.js 16, y luego cree un cliente singleton para evitar fugas de conexiones.
Esta guía muestra cómo configurar Prisma 7 dentro de una aplicación Next.js 16 que se comunica con PostgreSQL, utilizando TypeScript y pnpm como gestor de paquetes.
Paso 1: Agregar los paquetes de Prisma
pnpm add prisma @prisma/client @prisma/adapter-pg
- prisma — la herramienta de línea de comandos que utilizará para ejecutar migraciones, generar el cliente y gestionar su esquema.
- @prisma/client — la biblioteca de cliente generada a la que el código de su aplicación llamará directamente.
- @prisma/adapter-pg — el adaptador del controlador de PostgreSQL que Prisma 7 introdujo para conectarse a Postgres.
Con estos tres paquetes instalados, ya está listo para inicializar la configuración de Prisma.
Paso 2: Inicializar Prisma
pnpm dlx prisma init
Al ejecutarlo, se crean los archivos y carpetas básicos necesarios para comenzar.
prisma.config.ts
prisma/
└── schema.prisma
Comprensión de prisma.config.ts
Este archivo contiene la configuración que Prisma necesita para funcionar, incluyendo cómo se conecta a su base de datos y cómo se comporta el generador del cliente.
import "dotenv/config";
import { defineConfig } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
datasource: {
url: process.env["DATABASE_URL"],
},
});
Comprensión de schema.prisma
Cualquier tabla que planees almacenar en PostgreSQL aparecerá aquí eventualmente como una definición de modelo.
generator client {
provider = "prisma-client"
output = "../lib/generated/prisma"
}
datasource db {
provider = "postgresql"
}
// models that You want to create
Paso 3: Dirigir Prisma a tu base de datos
Prisma necesita una cadena de conexión antes de poder comunicarse con tu base de datos. Puedes obtenerla de un proveedor alojado como Neon, o ejecutando una instancia de Postgres localmente mediante Docker.
DATABASE_URL="postgresql://username:password@localhost:5432/my_database"
En cuanto se establece esta variable de entorno, Prisma puede acceder a tu base de datos.
Paso 4: Definir un modelo inicial
Prisma Client no puede generarse hasta que haya al menos un modelo en el esquema.
Dado que la base de datos está vacía en este momento, agregue un modelo de marcador mínimo solo para que Prisma tenga algo con lo que trabajar.
model Test {
id Int @id @default(autoincrement())
}
El objetivo aquí no es una tabla significativa; se trata simplemente de proporcionar al generador un esquema válido del cual partir.
Paso 5: Aplique su primera migración
A continuación, convierta ese esquema en tablas reales de la base de datos ejecutando una migración.
pnpm dlx prisma migrate dev
Este único comando maneja automáticamente varias cosas:
- Genera un nuevo archivo de migración.
- Aplica esa migración a la base de datos configurada.
- Mantiene la estructura de su base de datos en sincronía con lo declarado en
schema.prisma.
Una vez que finalice con éxito, la tabla Test existirá en su base de datos.
Paso 6: Generar el cliente Prisma
Uno de los cambios más notables en Prisma 7 es que el cliente ya no se genera automáticamente para usted.
Ahora debe iniciar la generación de forma explícita.
pnpm dlx prisma generate dev
Una vez finalizado este proceso, Prisma crea un cliente completamente tipado adaptado a su esquema.
Ese cliente expone todos los métodos que necesitará para consultar y modificar sus datos.
generated/
└── prisma/
Cada modelo definido en su esquema ahora se expone como una API de TypeScript tipada independiente.
Paso 7: Crear un cliente Prisma Singleton
En lugar de crear una nueva instancia del cliente Prisma en cada solicitud, la mejor práctica es reutilizar una única instancia compartida en toda la aplicación.
File: lib/prisma.ts
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "./generated/prisma/client";
const globalForPrisma = globalThis as unknown as {
prisma: PrismaClient | undefined;
};
function createPrismaClient() {
const url = process.env.DATABASE_URL;
if (!url) {
throw new Error("DATABASE_URL is not set");
}
const adapter = new PrismaPg({ connectionString: url });
return new PrismaClient({ adapter });
}
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
if (process.env.NODE_ENV !== "production") {
globalForPrisma.prisma = prisma;
}
Por qué es importante el Singleton aquí
Next.js vuelve a cargar los módulos en tiempo real constantemente mientras desarrolla.
Si se crea un nuevo PrismaClient en cada recarga, terminarás abriendo muchas más conexiones a la base de datos de las que pretendías.
Si no se controla, esto eventualmente se manifestará como un error similar a este:
Too many database connections
El uso del patrón Singleton garantiza que haya una única instancia de Prisma Client durante toda la vida útil de la aplicación.
Este es el enfoque que Prisma mismo recomienda para proyectos Next.js.
Paso 8: Utiliza el cliente en toda tu aplicación
Con la instancia del cliente compartida ya establecida, puedes importarla desde cualquier parte de tu proyecto.
import { prisma } from "@/lib/prisma";
A partir de aquí, cualquier componente del servidor, ruta API o acción del servidor tiene acceso directo a tu base de datos.
Para obtener más detalles sobre esta configuración, consulta la documentación oficial de Prisma para integración con Next.js, disponible en prisma.io/docs/guides/nextjs.
Lecturas relacionadas
- Creando plantillas iniciales reutilizables de Next.js para evitar el código genérico — Aprenda cómo un desarrollador reemplazó las tareas repetitivas de limpieza en Next.js por un conjunto cada vez mayor de plantillas iniciales mínimas para tiendas online y páginas de aterrizaje.
- Migrar de Prisma a Drizzle: Un retrospectivo de seis meses — Un desarrollador comparte resultados reales y consideraciones al cambiar una estructura basada en PostgreSQL y TypeScript de Prisma a Drizzle ORM.