Guía: Cómo integrar Prisma ORM en tu proyecto Next.js con PostgreSQL

Cómo integrar Prisma en tu proyecto Next.js existente

Prisma se ha convertido en el ORM favorito de muchos desarrolladores por su excelente autocompletado, seguridad de tipos y facilidad de uso. Si ya estás utilizando el trío dinámico de TypeScript, Next.js y shadcn/ui y quieres conectar una base de datos PostgreSQL de forma robusta, estás en el lugar correcto.

En esta guía, te mostraremos paso a paso cómo integrar Prisma usando el adaptador de Postgres, una solución ideal tanto para servidores tradicionales como para entornos serverless.

Paso a paso para la configuración técnica

1. Instalar dependencias

Primero, necesitamos instalar las herramientas de desarrollo de Prisma y los paquetes necesarios para la conexión con PostgreSQL. Ejecuta en tu terminal:

bash npm install prisma tsx @types/pg --save-dev npm install @prisma/client @prisma/adapter-pg dotenv pg

2. Inicializar Prisma

Inicializamos Prisma definiendo una ruta de salida personalizada para el cliente generado:

bash npx prisma init --output ../app/generated/prisma

Esto creará un directorio prisma/ con el archivo schema.prisma, un archivo prisma.config.ts y un .env con la variable DATABASE_URL.

3. Crear y conectar la base de datos

Si ya tienes tu propia base de datos PostgreSQL (algo común si has realizado una migración de Oracle a PostgreSQL), simplemente pega tu URL de conexión en el archivo .env.

4. Definir tu esquema

Abre prisma/schema.prisma y define tus modelos. Ejemplo:

prisma generator client { provider = "prisma-client-js" output = "../app/generated/prisma" }

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

model User { id Int @id @default(autoincrement()) email String @unique name String? posts Post[] }

model Post { id Int @id @default(autoincrement()) title String content String? published Boolean @default(false) authorId Int author User @relation(fields: [authorId], references: [id]) }

5. Configurar prisma.config.ts

Asegúrate de que tu archivo prisma.config.ts cargue correctamente las variables de entorno:

typescript import "dotenv/config"; import { defineConfig, env } from "prisma/config";

export default defineConfig({ schema: "prisma/schema.prisma", migrations: { path: "prisma/migrations", }, datasource: { url: env("DATABASE_URL"), }, });

6. Ejecutar migraciones y generar el cliente

Sincroniza tu base de datos y genera el código del cliente:

bash npx prisma migrate dev --name init npx prisma generate

Optimización y Cumplimiento Normativo

7. Crear el cliente Prisma reutilizable

En Next.js, para evitar agotar las conexiones en desarrollo, crea lib/prisma.ts:

typescript import { PrismaClient } from "../app/generated/prisma/client"; import { PrismaPg } from "@prisma/adapter-pg";

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL!, });

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

const prisma = globalForPrisma.prisma || new PrismaClient({ adapter });

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

export default prisma;

8. Uso en un Server Component

¡Listo! Ahora puedes consultar tu base de datos directamente:

typescript // app/page.tsx import prisma from "../lib/prisma";

export default async function Page() { const users = await prisma.user.findMany(); return (/* JSX */); }

Consideraciones de Seguridad y Datos en Chile

Al integrar bases de datos en aplicaciones modernas, es fundamental considerar la normativa local. El uso de un ORM como Prisma facilita la estructuración de datos, lo cual es un paso crítico para cumplir con la Ley 21.719 de Protección de Datos en Chile. Mantener un esquema claro y tipado te ayudará a auditar mejor cómo se maneja la información sensible de tus usuarios.

Si tu empresa está evaluando entre el uso de herramientas No-Code o desarrollo a medida, la implementación de Prisma en un stack de Next.js ofrece la escalabilidad necesaria para proyectos que requieren un alto rendimiento y control total sobre la infraestructura.