Prisma Server Actions en Next.js 16: los patrones que funcionan y el N+1 que aparece cuando no lo esperás

Next.js 16 salió hace poco con mejoras en el App Router y estabilización de Server Actions como primitiva de primera clase. La comunidad está adoptando Server Actions como el reemplazo natural de las API routes para mutaciones. La migración parece obvia — menos boilerplate, co-location con el componente, tipo compartido entre cliente y servidor. Yo también empecé a moverme en esa dirección. Y en algún punto del camino encontré un N+1 que no venía de Prisma: venía de cómo estaba componiendo las Actions.

Mi tesis es esta: Prisma ORM 5 no introduce N+1 en Server Actions. Lo introduce la composición de Server Actions — el patrón de llamar múltiples acciones independientes desde el mismo componente o encadenarlas sin colapsar las queries. Es un problema de arquitectura, no de ORM. Y tiene solución, pero hay que saber dónde mirar.

El N+1 clásico vs el N+1 de composición en Server Actions

En el N+1 clásico con Prisma, el problema es conocido: iterás sobre una lista y por cada ítem hacés una query separada porque olvidaste el include. La documentación oficial de Prisma sobre optimización lo documenta con precisión: la solución es usar include o select con relaciones nested, o en casos más complejos, findMany con filtros relacionales en lugar de queries en loop.

El N+1 de composición en Server Actions es diferente. No aparece en el cuerpo de una sola Action — aparece cuando el componente llama a varias Actions en secuencia o en paralelo, y cada Action abre su propia conexión con su propio cursor de Prisma. Bajo carga de SSR, eso se convierte en una presión sobre el connection pool que no aparece en tests locales.

Mirá este patrón problemático:

// app/dashboard/page.tsx
// ⚠️ Patrón problemático: tres Actions independientes
// cada una abre su propia conexión al pool

import { getUserProfile } from "@/actions/usuario"
import { getRecentOrders } from "@/actions/pedidos"
import { getNotifications } from "@/actions/notificaciones"

export default async function DashboardPage() {
  // Tres round-trips separados, tres conexiones del pool
  const perfil = await getUserProfile()
  const pedidos = await getRecentOrders()
  const notificaciones = await getNotifications()

  return <Dashboard perfil={perfil} pedidos={pedidos} notificaciones={notificaciones} />
}

Cada una de esas Actions tiene su propio prisma.user.findUnique, su propio prisma.order.findMany, su propio prisma.notification.findMany. Tres queries que podrían resolverse con una sola llamada bien diseñada — o al menos con Promise.all para paralelizarlas.

El connection pool bajo carga de SSR

Prisma usa un connection pool interno. En Next.js App Router con SSR, cada request puede disparar múltiples Server Actions en el mismo render. Si cada componente de la página llama su propia Action, el pool recibe una ráfaga corta pero intensa de conexiones por cada visita de usuario.

El patrón más común que genera este problema es el uso de prisma como singleton global junto con el PrismaClient instanciado en cada módulo separado. La documentación de Prisma recomienda explícitamente usar una instancia singleton en entornos serverless y SSR:

// lib/prisma.ts
// Patrón singleton recomendado por Prisma para Next.js
// Fuente: https://www.prisma.io/docs/orm/prisma-client/queries/query-optimization-performance

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", "warn", "error"] : ["error"],
  })

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

Si no usás este patrón, cada hot reload en desarrollo — y potencialmente cada cold start en producción con algunos providers — puede instanciar un PrismaClient nuevo con su propio pool. El resultado: conexiones agotadas sin advertencia obvia en los logs.

Los patrones que funcionan: colapsar queries en una sola Action

El antídoto al N+1 de composición es simple de enunciar pero requiere disciplina: una Action por caso de uso, no una Action por entidad. En lugar de tres Actions independientes para el dashboard, una sola Action que agrupa las tres queries con Promise.all:

// actions/dashboard.ts
// ✅ Patrón correcto: una Action que colapsa las queries
// Promise.all para paralelismo real dentro de la misma conexión

"use server"

import { prisma } from "@/lib/prisma"
import { auth } from "@/lib/auth"

export async function getDashboardData() {
  const session = await auth()
  if (!session?.user?.id) throw new Error("No autenticado")

  const userId = session.user.id

  // Una sola invocación al pool — tres queries en paralelo
  const [perfil, pedidos, notificaciones] = await Promise.all([
    prisma.user.findUnique({
      where: { id: userId },
      select: { nombre: true, email: true, avatarUrl: true },
    }),
    prisma.order.findMany({
      where: { userId, creadoEn: { gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) } },
      orderBy: { creadoEn: "desc" },
      take: 10,
    }),
    prisma.notification.findMany({
      where: { userId, leida: false },
      orderBy: { creadoEn: "desc" },
      take: 5,
    }),
  ])

  return { perfil, pedidos, notificaciones }
}

La diferencia no es solo de queries — es de diseño. Una Action que agrupa los datos de un caso de uso específico es más fácil de cachear, más fácil de testear y más honesta sobre qué problema está resolviendo.

El include que se olvidó y la query que se multiplicó

El N+1 clásico todavía existe dentro de las Actions. Si iterás resultados y hacés una query anidada por cada ítem, Prisma no lo va a prevenir solo — eso es tuyo. El patrón más frecuente que veo en codebases que empiezan con Server Actions:

// ⚠️ N+1 clásico dentro de una Action
// Una query por cada pedido para traer el producto

"use server"

import { prisma } from "@/lib/prisma"

export async function getPedidosConProductos(userId: string) {
  const pedidos = await prisma.order.findMany({ where: { userId } })

  // ❌ N+1: una query por cada pedido
  const pedidosConProducto = await Promise.all(
    pedidos.map(async (pedido) => {
      const producto = await prisma.product.findUnique({
        where: { id: pedido.productId },
      })
      return { ...pedido, producto }
    })
  )

  return pedidosConProducto
}

La solución correcta es colapsar con include:

// ✅ Include correcto: una sola query con JOIN implícito
// Prisma colapsa todo en un único round-trip

"use server"

import { prisma } from "@/lib/prisma"

export async function getPedidosConProductos(userId: string) {
  return prisma.order.findMany({
    where: { userId },
    include: {
      producto: {
        select: { nombre: true, precio: true, imagenUrl: true },
      },
    },
    orderBy: { creadoEn: "desc" },
    take: 20,
  })
}

El select dentro del include es importante: no traés el objeto completo de producto, traés exactamente los campos que el componente necesita. Eso reduce el payload serializado que Next.js tiene que transferir entre server y cliente.

Gotchas reales: lo que no aparece en el tutorial de 15 minutos

El "use server" no garantiza serialización automática de errores de Prisma. Si una Action lanza un PrismaClientKnownRequestError (por ejemplo, un constraint violation), ese error no llega al cliente de la forma que esperás en todos los casos. Necesitás wrapear con try/catch y serializar el error explícitamente:

// actions/usuario.ts
// Manejo explícito de errores de Prisma en Server Actions

"use server"

import { prisma } from "@/lib/prisma"
import { Prisma } from "@prisma/client"

export async function crearUsuario(data: { email: string; nombre: string }) {
  try {
    return await prisma.user.create({ data })
  } catch (error) {
    // Constraint unique violation (P2002 en Prisma)
    if (error instanceof Prisma.PrismaClientKnownRequestError) {
      if (error.code === "P2002") {
        return { error: "El email ya está registrado" }
      }
    }
    // Error no esperado: loguear, no exponer
    console.error("[crearUsuario]", error)
    return { error: "Error interno. Intentá de nuevo." }
  }
}

El logging de queries en desarrollo es tu mejor herramienta de diagnóstico. El singleton de arriba ya incluye log: ["query"] en desarrollo — eso te permite ver exactamente cuántas queries dispara cada render. Si ves el mismo SELECT repetido N veces en el terminal, tenés un N+1 y podés atacarlo antes de que llegue a producción.

Server Actions y React 19 useOptimistic pueden ocultar el problema. Si usás useOptimistic para actualizar la UI antes de que la Action resuelva, la percepción de latencia baja — pero las queries siguen estando. No confundas UX mejorada con queries optimizadas.

Esto conecta con algo que ya documenté al analizar cómo OpenTelemetry en Spring Boot muestra el problema real cuando el log dice OK: la superficie de observabilidad importa. En Next.js 16, si no tenés trazas de queries, el log de la Action puede parecer saludable mientras las queries se multiplican por debajo.

FAQ: Prisma Server Actions Next.js 16 N+1

¿Por qué aparece N+1 en Server Actions si no aparecía en mis API routes?
En API routes, el patrón natural era una ruta = un handler = una query. En Server Actions, la co-location con el componente invita a crear una Action por entidad, y los componentes terminan llamando varias Actions en el mismo render. Esa composición genera múltiples round-trips que en una API route no existían porque la query estaba centralizada.

¿Prisma ORM 5 tiene algún mecanismo para detectar N+1 automáticamente?
No automáticamente en runtime, pero sí podés habilitar el log de queries (log: ["query"]) para verlas en desarrollo. Hay propuestas en la comunidad para un detector de N+1 nativo, pero a la fecha de este post no es una feature estable. La documentación oficial de optimización documenta los patrones a evitar, pero la detección sigue siendo manual o via herramientas externas.

¿Cuántas instancias de PrismaClient debería tener en un proyecto Next.js 16?
Una sola, usando el patrón singleton con globalThis. Más de una instancia significa más de un connection pool, lo que bajo carga de SSR puede agotar las conexiones disponibles en la base de datos. Esto es especialmente crítico en providers serverless donde cada función puede tener su propio proceso.

¿Promise.all dentro de una Action es suficiente para resolver el problema de pool?
Para el caso de múltiples queries independientes dentro de una Action, sí: Promise.all las paraleliza dentro de la misma invocación y el pool maneja una sola conexión (o las mínimas necesarias). El problema que Promise.all no resuelve es cuando tenés múltiples Actions independientes disparadas desde distintos componentes del mismo render — ahí necesitás consolidar a nivel de arquitectura.

¿Cómo afecta esto al caching de Next.js 16?
Next.js 16 tiene caching de Data Cache y Full Route Cache. Si usás fetch o unstable_cache, podés cachear el resultado de una Server Action. Pero el N+1 ocurre antes del cache — si la Action no está cacheada (por ejemplo, en mutaciones o en datos con no-store), cada request ejecuta las queries. El patrón correcto es cachear la Action completa con unstable_cache cuando los datos lo permiten, no cachear queries individuales dentro de ella.

¿Este patrón aplica también a Prisma con Server Components puros (sin Actions)?
Sí, pero con una diferencia: en Server Components sin Actions, las queries viven en el componente directamente y Next.js puede hacer caching a nivel de componente más fácilmente. El problema de composición se acentúa con Server Actions porque el modelo mental de "una Action = un botón o formulario" lleva a granularidad excesiva que multiplica los round-trips.

Lo que me quedo y lo que no compro

Me quedo con este patrón: una Action por caso de uso, no una Action por entidad. Es el cambio de mentalidad más importante al migrar de API routes a Server Actions con Prisma.

Lo que no compro es la narrativa de que Server Actions simplifican el modelo de datos automáticamente. Simplifican el boilerplate — el tipo compartido, el endpoint explícito — pero la responsabilidad de no multiplicar queries sigue siendo tuya. Si venías de API routes donde una ruta = una query bien pensada, el salto a Actions puede llevar a una dispersión de queries que es peor.

El trade-off honesto: Server Actions ganan en DX y co-location. Pierden en visibilidad de qué queries se disparan por render si no tenés el logging activo. Antes de deployar cualquier página con múltiples Actions, revisá el terminal de desarrollo con log: ["query"] activo y contá cuántos SELECT aparecen por render. Si el número te sorprende, tenés trabajo por hacer.

Esto se conecta directamente con lo que documenté en Prisma vs JDBC: el benchmark que casi me hace culpar al ORM equivocado — el ORM rara vez es el problema. La forma de las queries sí lo es. Y en Next.js 16 con Server Actions, la forma la define la arquitectura de las Actions, no Prisma.

Para los que vienen del mundo Spring Boot, hay un paralelo interesante con el presupuesto de retry y amplificación: cada abstracción que parece simplificar introduce su propio vector de amplificación. En Server Actions, ese vector es la composición granular de queries.

Fuentes:

Prisma Docs — Query optimization & performance

Este artículo fue publicado originalmente en juanchi.dev

推荐订阅源

DEV Community