Next.js + Prisma + PostgreSQL

Configuración full-stack de Next.js 15 con Prisma ORM, base de datos PostgreSQL y Server Actions para mutaciones.

Receta

1. Scaffolding de una aplicación Next.js 15 con Tailwind y TypeScript:

   npx create-next-app@latest my-app --typescript --tailwind --app
   cd my-app

2. Instala Prisma y el cliente:

   npm install prisma @prisma/client
   npm install -D prisma

3. Inicializa Prisma con PostgreSQL:

   npx prisma init --datasource-provider postgresql

4. Define tu esquema en prisma/schema.prisma.
5. Establece DATABASE_URL en .env.
6. Ejecuta tu primera migración:

   npx prisma migrate dev --name init

7. Crea un singleton de cliente Prisma en lib/prisma.ts para evitar agotar conexiones durante la recarga en caliente.

Ejemplo Funcionando

Una aplicación Todo completa con Prisma + PostgreSQL + Server Actions.

prisma/schema.prisma

generator client \{
  provider = "prisma-client-js"
\}
 
datasource db \{
  provider = "postgresql"
  url      = env("DATABASE_URL")
\}
 
model Todo \{
  id        String   @id @default(cuid())
  title     String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
\}

lib/prisma.ts (singleton)

import \{ PrismaClient \} from "@prisma/client";
 
const globalForPrisma = globalThis as unknown as \{
  prisma: PrismaClient | undefined;
\};
 
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient(\{
    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
  \});
 
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

app/page.tsx (Server Component)

import \{ prisma \} from "@/lib/prisma";
import \{ addTodo \} from "./actions";
 
export default async function Home() \{
  const todos = await prisma.todo.findMany(\{
    orderBy: \{ createdAt: "desc" \},
  \});
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">Todos</h1>
 
      <form action=\{addTodo\} className="mt-4 flex gap-2">
        <input
          name="title"
          required
          className="flex-1 rounded border px-3 py-2"
          placeholder="Nuevo todo..."
        />
        <button type="submit" className="rounded bg-black px-4 py-2 text-white">
          Agregar
        </button>
      </form>
 
      <ul className="mt-6 space-y-2">
        \{todos.map((todo) => (
          <li key=\{todo.id\} className="rounded border p-3">
            \{todo.title\}
          </li>
        ))\}
      </ul>
    </main>
  );
\}

app/actions.ts (Server Action)

"use server";
 
import \{ prisma \} from "@/lib/prisma";
import \{ revalidatePath \} from "next/cache";
 
export async function addTodo(formData: FormData) \{
  const title = formData.get("title");
  if (typeof title !== "string" || title.trim() === "") return;
 
  await prisma.todo.create(\{
    data: \{ title: title.trim() \},
  \});
 
  revalidatePath("/");
\}

Análisis Profundo

Cómo Funciona

Prisma genera un cliente completamente tipificado basado en tu esquema. El Server Component de Next.js se ejecuta en el servidor y consulta Postgres directamente a través del cliente Prisma. Las Server Actions son puntos finales POST creados automáticamente por Next.js — el envío de formularios invoca la acción, que muta la base de datos y llama a revalidatePath para purgar el render almacenado en caché para que los nuevos datos aparezcan en la siguiente solicitud.

El patrón singleton es crítico en desarrollo. La recarga en caliente de Next.js re-evalúa módulos en cada cambio, y sin un singleton crearías un nuevo PrismaClient por recarga, agotando rápidamente el conjunto de conexiones de la base de datos.

Variaciones

• PostgreSQL alojado: Supabase, Neon, Railway o Vercel Postgres funcionan todos — simplemente pega su cadena de conexión en DATABASE_URL.
• Desarrollo local con SQLite: cambia provider = "sqlite" y usa url = "file:./dev.db" para una base de datos local sin configuración.
• Seeding: agrega un script prisma/seed.ts y regístralo bajo "prisma": \{ "seed": "tsx prisma/seed.ts" \} en package.json, luego ejecuta npx prisma db seed.
• Prisma Studio: ejecuta npx prisma studio para un navegador de datos y editor basado en navegador.
• Prisma Accelerate: agrupamiento de conexiones + almacenamiento en caché global a través de una URL única prisma://, ideal para despliegues serverless.
• ORM Alternativa: Drizzle ORM ofrece SQL tipificado y un runtime más ligero.

Notas TypeScript

• Prisma genera automáticamente tipos para cada modelo. Importa con import \{ Todo \} from "@prisma/client".
• Para resultados de consultas con relaciones, usa Prisma.TodoGetPayload<\{ include: \{ author: true \} \}> para derivar un tipo exacto de la forma de retorno.
• Las Server Actions se pueden tipificar como (formData: FormData) => Promise<void> o usar el patrón más reciente useActionState con un argumento prevState.
• Habilita modo estricto en tsconfig.json para detectar campos anulables — Prisma respeta ? en esquema como T | null en TS.

Trampas

1. Singleton o muere. Sin el singleton globalThis en lib/prisma.ts, el modo dev de Next.js filtrará conexiones hasta que Postgres rechace las nuevas.
2. DATABASE_URL faltante. Prisma no generará sin ella. Colócala en .env (no solo .env.local) porque la CLI de Prisma lee .env.
3. Olvida prisma generate. Después de cambiar schema.prisma, regenera el cliente o tus tipos se desviarán. prisma migrate dev lo hace automáticamente, pero prisma db push y ediciones manuales de esquema pueden no hacerlo.
4. Migraciones en producción. Usa prisma migrate deploy en CI/CD, nunca prisma migrate dev — esto último puede solicitar interactivamente y eliminar datos.
5. Objetivos binarios para despliegue. En plataformas como Vercel o AWS Lambda, es posible que debas agregar binaryTargets = ["native", "rhel-openssl-3.0.x"] al bloque generador, o tu despliegue fallará con "Binario de motor de consulta no encontrado".
6. Límites de conexión en serverless. Cada invocación de Lambda/Edge puede abrir una conexión nueva. Usa PgBouncer, Prisma Accelerate o una cadena de conexión agrupada.
7. Incompatibilidad de tiempo de ejecución Edge. El cliente Prisma estándar no se ejecuta en Edge. Usa Prisma Accelerate o la versión preliminar de Driver Adapters para soporte de Edge.

Alternativas

Preguntas Frecuentes

generator client \{
  provider      = "prisma-client-js"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
\}

import \{ Prisma \} from "@prisma/client";
 
type TodoWithAuthor = Prisma.TodoGetPayload<\{
  include: \{ author: true \};
\}>;

export async function addTodo(formData: FormData): Promise<void> \{ /* ... */ \}

export async function addTodo(prevState: State, formData: FormData): Promise<State> \{ /* ... */ \}

Relacionado

• Next.js Data: Server Actions
• React Libraries: Prisma
• Next.js Patterns: Environment Variables
• Next.js Data: Revalidation