Prisma query logging y PostgreSQL: dónde termina el ORM y empieza la base

Activé query logging en Prisma, vi los queries llegando a la consola, y asumí que tenía visibilidad completa sobre lo que pasaba en la base. Spoiler: no la tenía.

Los logs de Prisma muestran la query que el cliente envía y el tiempo que tardó desde la perspectiva del ORM — incluyendo serialización, red y el overhead del driver. Lo que no muestran es qué hace PostgreSQL con esa query adentro: si usó un índice, si hizo un sequential scan, si hubo lock wait, si el planner eligió mal el plan. Esa parte vive en Postgres, no en el ORM.

Mi tesis: los query logs de Prisma son una herramienta de debugging de patrones, no de diagnóstico de base de datos. Confundirlos lleva a buscar el problema en el lugar equivocado y a tomar decisiones de optimización sin evidencia real.

Qué dice la documentación oficial de Prisma — y qué no dice

La .

Necesitás mirar PostgreSQL directamente cuando:

• 
  La duración del cliente es alta pero el patrón de queries parece correcto: investigá pg_stat_statements para ver tiempo real en Postgres.


• 
  Sospechás un sequential scan: EXPLAIN ANALYZE en la misma query te dice si hay un índice que no se está usando.


• 
  Hay bloqueos o deadlocks: pg_locks y pg_stat_activity son las herramientas. Prisma no ve esto.


• 
  El problema aparece bajo carga pero no en local: puede ser contención del pool o autovacuum que se activa con volumen real. Ninguna de las dos cosas aparece en logs de ORM.


• 
  Querés entender el plan del query planner: el plan puede cambiar con los datos reales y con las estadísticas de la tabla. Solo EXPLAIN ANALYZE te lo muestra.
  

-- Corrés esto directamente en PostgreSQL para ver el plan real de ejecución

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)

SELECT u.id, u.email

FROM "Usuario" u

WHERE u.estado = 'activo'

ORDER BY u."creadoEn" DESC

LIMIT 50;



-- Buffers=true muestra cuántos bloques leyó de disco vs caché

-- Analyze=true ejecuta la query de verdad (cuidado en tablas con writes pesados)

Checklist de diagnóstico: por dónde empezar

Antes de optimizar algo, respondé estas preguntas en orden:

1. ¿El log de Prisma muestra muchas queries para una sola operación?

   → Sí: revisá N+1, eager loading, relaciones mal cargadas

   → No: seguí



2. ¿El SQL generado tiene sentido? ¿Traemos columnas que no usamos?

   → Problema: agregá select explícito en Prisma

   → OK: seguí



3. ¿La duración en Prisma es alta de forma consistente o esporádica?

   → Esporádica: investigá pool contention, conexiones agotadas

   → Consistente: seguí



4. ¿Tenés pg_stat_statements habilitado en PostgreSQL?

   → No: habilitarlo es el próximo paso antes de seguir diagnosticando

   → Sí: buscá la query por query text y mirá mean_exec_time real



5. ¿El plan de ejecución usa índice o sequential scan?

   → EXPLAIN ANALYZE en la query real con datos reales

   → Si hay seq scan en tabla grande con filtros, ahí está el problema

Límites claros: qué no podés concluir solo con Prisma logs

Esto importa y no lo suficiente gente lo dice:

• 
  No podés concluir que "la query es lenta" basándote solo en e.duration sin saber cuánto de ese tiempo es Postgres vs overhead del driver vs red.


• 
  No podés detectar lock waits ni deadlocks desde el cliente ORM. Un query que espera un lock va a aparecer con duración alta, pero el motivo es invisible desde Prisma.


• 
  No podés ver si autovacuum está compitiendo con tus writes. Ese ruido de fondo aparece como lentitud intermitente que no correlaciona con ningún patrón en el log del cliente.


• 
  No podés validar que un índice se está usando sin EXPLAIN. Que Prisma genere un WHERE correcto no garantiza que Postgres elija el índice que esperás.


• 
  No podés reproducir el comportamiento bajo carga real solo con logs locales. El pool tiene un tamaño máximo (configurable con connection_limit en el datasource), y la contención aparece cuando hay concurrencia real.

Si el diagnóstico requiere cualquiera de esos puntos, el log de Prisma es un punto de partida, no la respuesta.

FAQ: Prisma query logging y PostgreSQL

¿Cómo habilito el query logging en Prisma sin mandar todo a stdout?

Usá emit: 'event' en vez de emit: 'stdout' y manejás el evento prisma.$on('query', handler). Así podés filtrar, estructurar o mandarlo a tu sistema de logging sin contaminar la salida estándar en producción.

¿El duration del log de Prisma es el mismo que el tiempo de ejecución en PostgreSQL?

No. La duración del cliente Prisma incluye serialización, latencia de red y overhead del driver. El tiempo real de ejecución en Postgres lo obtenés con pg_stat_statements o EXPLAIN ANALYZE. Pueden diferir bastante dependiendo del tamaño del resultado y la latencia de red.

¿Cómo habilito pg_stat_statements en PostgreSQL?

Agregás pg_stat_statements a shared_preload_libraries en postgresql.conf, reiniciás el servidor y ejecutás CREATE EXTENSION IF NOT EXISTS pg_stat_statements; en la base. Desde ahí podés consultar pg_stat_statements para ver tiempos de ejecución reales por query.

¿Tiene sentido loguear queries en producción?

Depende del volumen. En producción con tráfico alto, loguear cada query puede generar overhead de I/O significativo. Una alternativa más prudente es loguear solo queries que superen un threshold de duración, o usar OpenTelemetry con sampling. El tema de observabilidad con trazas lo cubrí en el contexto de Spring Boot pero los principios son similares — más detalles en el

Este artículo fue publicado originalmente en juanchi.dev