Todo el curso ha ejecutado SQL desde psql: escribes, pulsas Intro, lees el resultado. En una aplicación real nada de eso pasa. Hay un proceso web que atiende cientos de peticiones por segundo, cada una con unos milisegundos de presupuesto, que no puede permitirse abrir una conexión, que ejecuta las consultas desde código en otro lenguaje, que muchas veces no las escribe siquiera —las genera un ORM— y en el que un error de diseño no se manifiesta como un mensaje sino como "la web va lenta desde ayer".

Esta lección es ese entorno: cómo se conecta una aplicación, cómo ejecuta y cómo gestiona sus transacciones, qué aporta y qué quita un ORM, los cuatro antipatrones que matan una web —empezando por el N+1 que 08-04 dejó pendiente—, los patrones que sí funcionan y la lista de comprobación para cuando algo va mal. Con ella se cierra el módulo y quedas listo para el proyecto final.

1. La conexión y el pool
2. Ejecutar SQL desde el código
3. ORM frente a SQL a mano
4. Los antipatrones que matan una web
5. Patrones útiles
6. Operación: despliegue, monitorización y timeouts
7. "La web va lenta": lista de comprobación
8. Errores Comunes y Consejos
9. Ejercicios
10. Conclusión del módulo

Una conexión a PostgreSQL empieza con una cadena de conexión, que en formato URI es la forma canónica:

Cuatro cosas que hay que mirar siempre: el usuario —web_prod, no el superusuario ni el propietario (11-03)—; el sslmode, que debe ser al menos require y preferiblemente verify-full, porque prefer acepta silenciosamente una conexión sin cifrar; el application_name, que aparecerá en pg_stat_activity y te dirá qué servicio está lanzando la consulta que ahoga la base; y que la clave nunca está en el repositorio, sino en una variable de entorno o en un gestor de secretos.

Abrir una conexión a PostgreSQL es caro. No es un socket y ya: el servidor crea un proceso del sistema operativo por conexión, negocia TLS, autentica e inicializa su memoria. Son del orden de decenas de milisegundos, frente a los 0,2 ms que tarda la consulta que ibas a lanzar. Si abres y cierras una conexión por petición, el 99 % del tiempo se va en la conexión.

Y no se arregla abriendo muchas y dejándolas abiertas: cada conexión ociosa consume memoria y max_connections (por omisión 100) tiene un límite que, superado, hace fallar las peticiones. La solución es un pool: un conjunto pequeño de conexiones ya abiertas que las peticiones toman prestadas y devuelven.

El tamaño sorprende a todo el mundo: es pequeño. Una regla de partida muy usada es núcleos × 2 + husos de disco, que para una máquina normal da entre 10 y 20 conexiones, no doscientas. El motivo es que la base de datos no va más rápido por recibir más peticiones a la vez: si tiene 8 núcleos, 200 consultas simultáneas no se ejecutan en paralelo, se pelean. Un pool pequeño encola en la aplicación, que es donde se puede esperar ordenadamente, en lugar de saturar el servidor.

⚠️ Cuidado con multiplicar. El límite que importa es el total: 8 instancias de la aplicación con un pool de 20 son 160 conexiones, más las del proceso de tareas, más las de los informes. Ese número tiene que caber en max_connections, con margen para las conexiones de administración.

Cuando hay muchas instancias, o cuando la plataforma crea procesos por petición (el modelo clásico de PHP), se pone un pooler externo: PgBouncer se sitúa entre la aplicación y PostgreSQL y multiplexa cientos de conexiones de cliente sobre unas pocas reales.

El modo transaction tiene letra pequeña y hay que conocerla: como la conexión cambia entre transacciones, deja de funcionar todo lo que vive en la sesión — sentencias preparadas con nombre, SET de sesión (usa SET LOCAL), tablas temporales, LISTEN/NOTIFY y los advisory locks de sesión de 09-05. Si tu ORM usa preparadas con nombre, hay que desactivarlas o usar una versión de PgBouncer que las soporte.

Tres piezas, con lo aprendido en 11-03 y en el módulo 9:

Una consulta, cinco filas, todo lo que la pantalla necesita: el nombre del cliente, el estado, el total y el número de líneas. Guarda esta consulta, porque el apartado 4 la va a comparar con la versión que lanza una consulta más por cada pedido de la lista.

Al insertar necesitas el id generado. La forma correcta es RETURNING (05-02), no un SELECT MAX(id) posterior —que además es incorrecto con concurrencia—:

El patrón de 09-03, escrito en código. Todo lo que debe pasar junto va dentro del mismo bloque:

Cuatro reglas que se aprenden a base de incidentes: rollback en todo error, porque una transacción abierta mantiene bloqueos y bloquea el VACUUM (09-02); devolver la conexión en el finally, o el pool se agota y la aplicación se congela entera; mantener la transacción lo más corta posible (apartado 4); y distinguir el error esperado del inesperado — una violación de UNIQUE es un mensaje al usuario, no un error 500.

Un ORM (Object-Relational Mapper) traduce entre las tablas y los objetos del lenguaje: Pedido.objects.filter(estado="pagado") se convierte en un SELECT.

El criterio del curso: ORM para el CRUD, SQL a mano para los informes y las consultas críticas. No es un término medio cobarde: es que las dos cosas son problemas distintos. "Guardar un pedido y sus líneas" es exactamente lo que un ORM hace bien. "La facturación mensual con acumulado, media móvil y variación" es exactamente lo que hace mal.

Y este es el ejemplo concreto, la consulta del apartado 2: un JOIN a dos tablas, un LEFT JOIN que no debe perder pedidos, un GROUP BY, una expresión de importe con descuento y un ORDER BY con desempate. Ningún ORM la escribe bien sin ayuda: o hace tres consultas, o trae objetos completos para contar sus líneas en memoria, o genera un GROUP BY con todas las columnas del modelo. Escríbela a mano, guárdala en un fichero .sql del repositorio (11-02) y ejecútala con el conector del ORM — todos permiten hacerlo. Y cuando lo hagas, sigue parametrizando: el raw()/text()/$queryRaw es exactamente donde vuelve la inyección SQL (11-03).

21 consultas frente a 1 para pintar la misma tabla. Y lo que hace grave al N+1 es cómo escala, porque el coste no es el tiempo de cada consulta sino el coste fijo que se paga en cada una: viaje de red, análisis, planificación:

Cómo detectarlo: cuenta las consultas por petición. Un contador en el middleware que registre "esta petición ha hecho 61 consultas" encuentra un N+1 en cinco minutos; pg_stat_statements lo delata como una consulta con mean_exec_time mínimo y un número de calls disparatado, que es la razón de ordenar por tiempo total. Las herramientas de cada entorno: django-debug-toolbar, Rails Bullet, Laravel Telescope, Hibernate statistics.

Sobre los 20 pedidos del curso, la segunda con (:ultima_fecha, :ultimo_id) = ('2026-01-13', 17) devuelve los pedidos 16, 15, 14, 13 y 12 con LIMIT 5: exactamente la página siguiente a la del apartado 2, sin releer nada.

Es lo de 09-01 llevado al mundo real, y el daño va más allá de esa petición: una transacción larga impide que VACUUM limpie las versiones antiguas de fila en toda la base (09-02), así que una sola petición lenta degrada a todas las demás. Vigila idle in transaction y pon idle_in_transaction_session_timeout.

La forma sistemática de encontrarlos: lista las pantallas, y para cada una escribe el WHERE y el ORDER BY que ejecuta. Esa lista es tu lista de índices candidatos — y solo esa, porque cada índice que sobra frena todas las escrituras (08-02).

• Paginación por cursor para scroll infinito y APIs. La respuesta lleva un next_cursor opaco (la tupla de la última fila, codificada) y el cliente lo devuelve. Coste constante y sin filas repetidas o perdidas cuando alguien inserta mientras el usuario navega.
• Filtros opcionales con el patrón de 11-01, y LIMIT defensivo en toda consulta expuesta al usuario: aunque la interfaz solo permita pedir 50, la API debe imponer un máximo (LEAST(:limite, 100)). Sin él, alguien pedirá ?limit=1000000 el día que más tráfico tengas.
• Caché para lo que cambia poco y se lee mucho: el catálogo, las categorías, la portada. Y con el aviso de siempre: la invalidación es el problema difícil. Empieza por caducidad por tiempo, que es sencilla y predecible, y deja la invalidación por eventos para cuando la necesites de verdad.
• Colas de trabajos con SELECT ... FOR UPDATE SKIP LOCKED (09-05). Varios procesos trabajadores toman tareas de la misma tabla sin pisarse ni esperarse: cada uno se salta las filas ya bloqueadas por otro. Es el patrón canónico para enviar correos, generar facturas o procesar imágenes sin montar un sistema de colas aparte.

• JSON directamente desde PostgreSQL (10-06): jsonb_build_object + jsonb_agg devuelven el pedido con sus líneas anidadas en una fila y una consulta, en lugar de traer filas planas y reensamblarlas en el lenguaje. Cuándo compensa: respuestas muy anidadas que la aplicación solo reenvía tal cual. Cuándo no: si la aplicación tiene que recorrer, validar o transformar el objeto —entonces prefiere filas tipadas—, si el JSON se vuelve enorme, o si mezclarlo con el ORM obliga a mantener dos formas de leer lo mismo.

Durante un despliegue conviven, aunque sea unos segundos, el código nuevo y el viejo. Si la migración y el código se despliegan a la vez y la migración rompe el esquema anterior, la versión antigua falla mientras dure el cambio. De ahí el expand/contract de 05-06, en tres despliegues:

Y dos detalles operativos que evitan una caída: CREATE INDEX CONCURRENTLY, porque un CREATE INDEX normal bloquea las escrituras de la tabla mientras se construye; y lock_timeout corto antes de un ALTER TABLE, para que la migración falle en tres segundos en lugar de encolar todas las consultas detrás de un bloqueo que no consigue (09-05).

Ordena por total_exec_time, no por la media: es lo único que hace visible el N+1, cuya media es minúscula y cuyo total es enorme. Y tres ajustes que deberían estar puestos desde el primer día:

Ponlos por rol: ALTER ROLE web_prod SET statement_timeout = '10s'; deja que los informes y las migraciones, con otros roles, tengan sus propios límites.

En este orden, porque va de lo más probable y barato a lo más raro y caro:

1. ¿Es todo o una pantalla? Si es una, mira sus consultas; si es todo, sospecha del servidor, del pool o de un bloqueo.
2. ¿Cuántas consultas hace esa petición? Un contador. Si son decenas, es un N+1 y ya has terminado.
3. ¿Se agota el pool? Si las peticiones esperan a obtener conexión, el problema no está en la base: es el pool, o transacciones que no se cierran. Mira idle in transaction.
4. pg_stat_statements por tiempo total. Las tres primeras consultas suelen explicar el 80 % de la carga.
5. EXPLAIN ANALYZE de la sospechosa (08-05). ¿Seq Scan donde debería haber índice? ¿Estimaciones lejanas de la realidad?
6. ¿Hay bloqueos? pg_locks con pg_stat_activity: una consulta en Lock no es lenta, está esperando (09-05).
7. ¿Han cambiado las estadísticas o el volumen? ¿Hubo carga masiva sin ANALYZE (08-04)?
8. ¿Se traen filas de más? Una consulta rápida que devuelve 200 000 filas satura la red y la memoria de la aplicación.
9. Y solo entonces, el servidor: CPU, memoria, disco, VACUUM pendiente, número de conexiones.

La regla es la de 08-04 aplicada a la web: mide antes de tocar. Y cuenta consultas, no solo milisegundos, porque el problema más común de todos no aparece en ningún ranking de consultas lentas.

• Abrir una conexión por petición. El coste de conexión supera con mucho al de la consulta. Usa un pool.
• Configurar el pool con 200 conexiones "por si acaso". La base no va más rápido por recibir más a la vez; el pool pequeño encola donde se puede esperar. Y recuerda multiplicar por el número de instancias.
• No devolver la conexión al pool. Un return en medio de un try sin finally agota el pool y congela la aplicación entera.
• Dejar una transacción abierta durante una llamada externa. Bloqueos, idle in transaction y un VACUUM que no puede trabajar.
• Confiar en que el ORM hará lo correcto. Mira el SQL que genera: casi todos tienen un modo de registro. Lo que no miras, no lo sabes. Y usar raw() concatenando: ahí vuelve la inyección (11-03).
• Paginar con OFFSET en una API. Lento en páginas profundas y con filas repetidas o perdidas si alguien inserta.
• No poner LIMIT en una consulta expuesta al usuario. Alguien pedirá un millón de filas.
• Desplegar migración y código a la vez con un cambio rompedor. Expand/contract, y CREATE INDEX CONCURRENTLY.
• Consejo: registra el número de consultas y el tiempo de base de datos de cada petición. Con esas dos métricas, los problemas de este apartado se ven antes de que los vea un usuario.
• Consejo: pon application_name en la cadena de conexión. Cuando la base sufra, sabrás qué servicio la está machacando en lugar de adivinarlo.
• Consejo: guarda las consultas complejas en ficheros .sql del repositorio, no incrustadas entre líneas de código. Se revisan mejor, se prueban en psql y se pueden formatear (11-02).

La ficha de cliente muestra sus datos, sus pedidos y, por cada pedido, sus líneas con el nombre del producto y su categoría. El registro dice 23 consultas por carga en la ficha de Lucía.

1. ¿De dónde salen exactamente las 23? (Pista: Lucía tiene 3 pedidos, de 3 líneas cada uno.)
2. Reduce la ficha a dos consultas y escríbelas.
3. ¿Por qué dos y no una?

Tu aplicación corre en 6 instancias, cada una con un pool de 25 conexiones. Hay además un proceso de tareas en segundo plano con 10 y un servidor de informes con 5. max_connections está en 100.

1. ¿Cuál es el problema y qué error verán los usuarios?
2. Da tres soluciones, de la más barata a la más cara.
3. Si eliges PgBouncer en modo transaction, ¿qué tienes que revisar en el código?

Una API devuelve el detalle de un pedido con su cliente y sus líneas. El equipo debate entre (a) tres consultas y reensamblar en el código, (b) una consulta con JOIN y reensamblar, (c) una consulta que devuelve el JSON ya montado (10-06).

1. Escribe la opción (c) para el pedido 1 y di qué devuelve.
2. Da un argumento a favor y uno en contra de cada opción.
3. ¿Cuál elegirías si la API tiene que devolver 50 pedidos en la misma respuesta?

Solución 1

1. 1 para el cliente + 1 para su lista de pedidos + 3 (una por pedido, para traer sus líneas) + 9 (una por línea, para el nombre del producto) + 9 (una por línea, para la categoría del producto) = 23. Es un N+1 anidado: cada nivel de la plantilla multiplica al anterior, y por eso el número crece tan deprisa. Con un cliente de 20 pedidos de 5 líneas serían 1 + 1 + 20 + 100 + 100 = 222 consultas para una sola pantalla.

2. Dos consultas: una para la cabecera de los pedidos y otra para todas sus líneas de una vez, con el producto ya unido.

Para Lucía (cliente 1), la primera devuelve 3 filas —los pedidos 1, 5 y 15, con 42,10 €, 32,10 € y 33,40 €, que suman sus 107,60 € canónicos— y la segunda, 9 filas. Fíjate en = ANY(%(ids)s) con un array: es la forma correcta de pasar una lista de identificadores sin construir el SQL concatenando (11-03).

3. Porque cabecera y detalle tienen cardinalidades distintas. Con una sola consulta, el total del pedido se repetiría en cada una de sus líneas y habría que deduplicarlo en el código, o habría que agregar las líneas a JSON. Dos consultas, cada una con la granularidad de lo que devuelve, son más claras y más eficientes que una que multiplica filas. La regla del "carga anticipada" de todos los ORM es exactamente esta: una consulta por nivel, no una por elemento.

Solución 2

1. 6 × 25 + 10 + 5 = 165 conexiones posibles contra un max_connections de 100. En cuanto haya carga, PostgreSQL rechazará las nuevas con FATAL: sorry, too many clients already, y los usuarios verán errores 500 intermitentes — intermitentes y por tanto difíciles de diagnosticar, porque solo aparecen en los picos. Peor aún, puede impedir incluso conectarse para administrar si no quedan huecos reservados (superuser_reserved_connections).

2. (a) Bajar el tamaño del pool a 10 por instancia: 6 × 10 + 10 + 5 = 75, con margen. Es gratis, inmediato y probablemente no empeorará el rendimiento, porque 165 consultas simultáneas no caben en los núcleos de la máquina de todos modos. (b) Poner PgBouncer en modo transaction: cientos de conexiones de cliente sobre 20 reales. (c) Subir max_connections y la memoria del servidor: es la más cara, exige reinicio y solo traslada el problema, porque cada conexión es un proceso con su memoria.

3. Con transaction la conexión cambia entre transacciones, así que hay que revisar: sentencias preparadas con nombre (muchos conectores las usan por omisión: desactivarlas o usar la versión de PgBouncer que las soporta), SET de sesión (cambiar a SET LOCAL dentro de la transacción — incluido el SET app.usuario de la auditoría de 11-01 y el de RLS de 11-03), tablas temporales, LISTEN/NOTIFY y advisory locks de sesión (09-05). Todo lo que dependa de "seguir en la misma sesión" deja de funcionar.

Solución 3

1. Es la consulta de 10-06: jsonb_build_object con el id, la fecha y los portes, el cliente anidado en otro objeto y las líneas en un jsonb_agg correlacionado. Devuelve una fila y una columna con el pedido 1 completo: Lucía Martínez Soler, España, y sus tres líneas —aceite 23,90 €, arroz 11,70 € e infusión 6,50 €— que suman los 42,10 € del pedido.

2. (a) Tres consultas: a favor, es la más simple y cada consulta es trivial de cachear e indexar; en contra, son tres viajes de red. (b) JOIN y reensamblar: a favor, un solo viaje y datos tipados que la aplicación puede transformar; en contra, repite la cabecera en cada línea y obliga a agrupar en el código, que es trabajo manual y propenso a errores. (c) JSON desde PostgreSQL: a favor, un viaje y cero código de reensamblado; en contra, la aplicación recibe un texto opaco que no puede transformar sin analizarlo, se pierde el tipado y se acopla la forma de la respuesta de la API al SQL — cambiar un campo del contrato obliga a tocar la consulta.

3. Con 50 pedidos, (c), y por un motivo concreto: es la única que no crece en número de viajes ni obliga a agrupar 50 cabeceras con sus ~120 líneas en el código. La (a) se convertiría en un N+1 si se hace por pedido —habría que reescribirla como dos consultas con = ANY(...), que es la solución del ejercicio 1—, y la (b) devolvería 120 filas con la cabecera repetida. La condición para que (c) sea buena idea sigue siendo la misma: que la API reenvíe el JSON tal cual. Si tiene que tocarlo, vuelve la (a) en su versión de dos consultas.

Así llega el SQL a una aplicación real:

• La conexión lleva usuario de mínimo privilegio, TLS (verify-full, no prefer) y application_name, y la clave nunca en el repositorio. Y va siempre por un pool, porque abrir una conexión cuesta decenas de milisegundos y cada una es un proceso en el servidor. El tamaño es pequeño —10-20 por instancia— y hay que multiplicarlo por el número de instancias. PgBouncer en modo transaction multiplexa cientos de clientes sobre pocas conexiones reales, a cambio de perder todo lo que vive en la sesión.
• Desde el código: consultas parametrizadas (11-03), RETURNING para el id (05-02) y el bloque try / commit / except rollback / finally putconn (09-03), con la transacción lo más corta posible y la conexión devuelta siempre.
• ORM frente a SQL: el ORM da mapeo, migraciones, seguridad por defecto y productividad; quita control del SQL y previsibilidad del rendimiento. El criterio: ORM para el CRUD, SQL a mano para los informes y las consultas críticas — como el listado de últimos pedidos, que ningún ORM escribe bien.
• Los antipatrones: el N+1, que convierte 1 consulta en 21 o en 501 y no aparece en ningún ranking de consultas lentas —cierra la promesa de 08-04—; traer todo y paginar en memoria, que se arregla con LIMIT y con keyset; la transacción abierta esperando una API externa, que retiene bloqueos y frena el VACUUM de toda la base; y la falta de índices en las columnas por las que filtra la web, empezando por las claves foráneas.
• Los patrones: paginación por cursor, filtros opcionales, LIMIT defensivo en toda consulta expuesta, caché con caducidad por tiempo, colas con SKIP LOCKED y JSON directo desde PostgreSQL cuando la API solo reenvía.
• La operación: migraciones compatibles hacia atrás en expand/contract, CREATE INDEX CONCURRENTLY, lock_timeout antes de un ALTER, pg_stat_statements ordenado por tiempo total, y statement_timeout e idle_in_transaction_session_timeout por rol. Más la lista de nueve puntos para cuando "la web va lenta", que empieza por contar consultas.

Y con esto se cierra el módulo 11 y, con él, el aprendizaje. En cinco lecciones has pasado de conocer el lenguaje a conocer el oficio: los casos de uso que reaparecen en todos los proyectos y qué herramienta resuelve cada uno; las mejores prácticas de nomenclatura, formato, diseño, fiabilidad y proceso, con su catálogo de antipatrones y su checklist; la seguridad, con la inyección SQL y su única defensa real, el modelo de roles y permisos de PostgreSQL y el trato de los datos personales; el análisis de datos, donde las funciones de ventana se convirtieron en informes y donde aprendiste que definir y validar importa más que consultar; y el desarrollo web, donde el SQL se ejecuta de verdad.

Queda una cosa, y es la única que no se aprende leyendo: hacerlo tú. En el módulo 12, Proyecto final, montarás un sistema completo de principio a fin: la descripción del proyecto y su contexto de negocio, los requisitos que debe cumplir, la implementación paso a paso —modelo, DDL, datos, consultas, índices, vistas, seguridad y rendimiento—, las soluciones comentadas con las decisiones justificadas una a una, y la presentación de los resultados. Todo lo de doce módulos, junto y en un solo trabajo. Es el momento de dejar de seguir un curso y empezar a construir.