<?xml version="1.0" encoding="utf-8" standalone="yes"?><?xml-stylesheet href="/feed_style.xsl" type="text/xsl"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="https://www.rssboard.org/media-rss"><channel><title>Podman – El blog de Ignacio</title><link>https://www.igalvan.es/tags/podman/</link><description>Entradas de Podman en El blog de Ignacio</description><generator>Hugo -- gohugo.io</generator><language>es</language><copyright>Ignacio Galván Vitas</copyright><lastBuildDate>Sun, 08 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://www.igalvan.es/tags/podman/index.xml" rel="self" type="application/rss+xml"/><icon>https://www.igalvan.es/logo.svg</icon><item><title>Podman rootless sin sudo ni Docker: de `podman run` a un servicio con Quadlet</title><link>https://www.igalvan.es/posts/2026/podman-rootless-sin-sudo-ni-docker/</link><pubDate>Sun, 08 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/podman-rootless-sin-sudo-ni-docker/</guid><description><![CDATA[<p>Hay un momento, con casi cualquier contenedor que montas «un momento para
probar», en el que se convierte en un servicio de verdad. Alguien lo usa. Tú
dependes de él. Y entonces te das cuenta de que <strong>su configuración entera vive
en el historial de tu shell</strong>: un <code>podman run</code> con cuatro volúmenes, tres
puertos y media docena de variables que ya no recuerdas del todo. Reinicia el
equipo y el contenedor no vuelve. Pierde el comando y has perdido el servicio.</p>
<p>Esta entrada va de las dos cosas que hacen falta para salir de ahí sin
privilegios:</p>
<ol>
<li><strong>Entender qué significa ejecutar contenedores rootless</strong> (sin demonio y sin
root), porque casi todos los problemas que vas a encontrar salen de ahí.</li>
<li><strong>Dejar de escribir <code>podman run</code> a mano</strong>, describiendo los contenedores en
ficheros que systemd arranca, reinicia y vigila: eso se llama <em>Quadlet</em>.</li>
</ol>
<p>Todo el código está en un laboratorio que puedes ejecutar. Las salidas de
terminal de las secciones sobre permisos son reales, capturadas con <strong>Podman
4.9.3 en Ubuntu 24.04</strong> con un usuario sin privilegios. Verás al final qué
partes he podido probar y cuáles no. Y si prefieres verlo en marcha, tienes
<a href="https://www.dailymotion.com/video/xbuxh4i" target="_blank" rel="noopener">la versión en vídeo</a>.</p>
<h2 id="qué-es-rootless-y-por-qué-importa">Qué es «rootless» y por qué importa <a class="ancla" href="#qu%c3%a9-es-rootless-y-por-qu%c3%a9-importa" aria-label="Enlace a esta sección">#</a></h2>
<p>Con Docker, las órdenes las ejecuta un demonio (<code>dockerd</code>) que corre como root.
Tu usuario le habla por un socket, y quien puede hablar con ese socket (el
grupo <code>docker</code>) puede, en la práctica, hacer lo que quiera en la máquina: es
equivalente a tener root sin escribir <code>sudo</code>.</p>
<p>Podman es distinto en dos cosas:</p>
<ul>
<li><strong>No hay demonio.</strong> Cada <code>podman run</code> es un proceso normal de tu usuario que
lanza el contenedor. No hay ningún servicio privilegiado escuchando.</li>
<li><strong>El contenedor corre con tu usuario</strong>, dentro de un <em>user namespace</em>. El
<code>root</code> que ves dentro es, para el sistema, tu usuario normal. Si algo se
escapa del contenedor, se escapa con tus permisos, no con los de root.</li>
</ul>
<p>El truco es una tabla de correspondencia de UIDs. Dentro de un contenedor hay
muchos usuarios (root, www-data, postgres&hellip;), pero tu usuario real es uno solo.
Por eso el sistema te reserva un rango de UIDs «subordinados» en <code>/etc/subuid</code> y
<code>/etc/subgid</code>, y Podman mapea los UIDs de dentro a ese rango. Puedes ver el mapa
de tu sesión:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ podman unshare cat /proc/self/uid_map
</span></span><span style="display:flex;"><span>         <span style="color:#ae81ff">0</span>      <span style="color:#ae81ff">30033</span>          <span style="color:#ae81ff">1</span>
</span></span><span style="display:flex;"><span>         <span style="color:#ae81ff">1</span>     <span style="color:#ae81ff">165536</span>      <span style="color:#ae81ff">65536</span></span></span></code></pre></div>
</div>
<p>Cada fila dice: <em>UID de dentro, UID de fuera, cuántos</em>. Aquí el usuario es el
30033 (el tuyo será probablemente el 1000). Lo que significa:</p>
<ul>
<li>El UID 0 de dentro (root) <strong>es tu usuario</strong> de fuera.</li>
<li>Los UIDs 1 a 65536 de dentro son del 165536 en adelante de fuera. Es decir, el
UID <code>N</code> de dentro es el <code>165535 + N</code> de fuera.</li>
</ul>
<p>Guarda esa fórmula. Explica los dos tercios de los problemas de permisos que
vas a encontrar.</p>
<h2 id="instalación-y-comprobaciones">Instalación y comprobaciones <a class="ancla" href="#instalaci%c3%b3n-y-comprobaciones" aria-label="Enlace a esta sección">#</a></h2>
<p>Instalar sí necesita privilegios, una vez:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ sudo apt install podman uidmap</span></span></code></pre></div>
</div>
<p><code>uidmap</code> aporta <code>newuidmap</code> y <code>newgidmap</code>, los programas que permiten a un
usuario normal crear el mapa anterior. A partir de ahí no hace falta <code>sudo</code> para
nada más. El laboratorio trae un script de diagnóstico que lo comprueba todo y no
modifica nada:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~/lab-podman$ ./comprobar.sh
</span></span><span style="display:flex;"><span>Diagnóstico para el usuario: usuario <span style="color:#f92672">(</span>uid 1000<span style="color:#f92672">)</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span> OK  <span style="color:#f92672">]</span> podman instalado: podman version 4.9.3
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span> OK  <span style="color:#f92672">]</span> podman funciona en modo rootless
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span> OK  <span style="color:#f92672">]</span> /etc/subuid: usuario:100000:65536
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span> OK  <span style="color:#f92672">]</span> /etc/subgid: usuario:100000:65536
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span> OK  <span style="color:#f92672">]</span> newuidmap y newgidmap disponibles
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span> OK  <span style="color:#f92672">]</span> generador de Quadlet: /usr/lib/systemd/system-generators/podman-system-generator
</span></span><span style="display:flex;"><span>...</span></span></code></pre></div>
</div>
<p>(La salida de arriba la he recortado y adaptado al usuario genérico; la
original, tal cual salió en mi entorno de pruebas, está en
<code>salidas/comprobar-sandbox.txt</code> y es interesante: ese entorno no tenía una
sesión de login real y el script lo detecta y lo explica.)</p>
<p>Qué comprueba y por qué importa cada cosa:</p>
<ul>
<li><strong><code>podman info</code> dice <code>Rootless: true</code>.</strong> Si no, algo falta (casi siempre
<code>uidmap</code> o el rango de subuid).</li>
<li><strong>Entradas en <code>/etc/subuid</code> y <code>/etc/subgid</code>.</strong> Sin ellas Podman no puede crear
el espacio de usuario. Las añade root con <code>usermod --add-subuids</code> y
<code>--add-subgids</code> (en Ubuntu suelen venir ya con el usuario).</li>
<li><strong>El generador de Quadlet</strong>, que existe desde Podman 4.4.</li>
<li><strong>Una sesión de login real</strong>: <code>systemctl --user</code> necesita <code>XDG_RUNTIME_DIR</code>, que
no existe tras un <code>su</code> o <code>sudo -u</code>.</li>
<li><strong>El linger</strong>, del que hablaré más abajo.</li>
<li><strong>El umbral de puertos sin privilegios</strong>, que también.</li>
</ul>
<p>Una prueba de humo, con nombre de imagen <strong>completo</strong>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ podman run --rm docker.io/library/alpine:3 echo hola
</span></span><span style="display:flex;"><span>hola</span></span></code></pre></div>
</div>
<p>Escribo <code>docker.io/library/alpine:3</code> y no <code>alpine</code> porque con nombres cortos
Podman tiene que adivinar en qué registro buscar y, sin terminal interactiva,
puede fallar o preguntarte. Con el nombre completo eres explícito, y Quadlet
además lo recomienda. Fíjate también en que puedes usar imágenes de cualquier
registro (<code>docker.io</code>, <code>quay.io</code>, <code>ghcr.io</code>&hellip;): no tener Docker instalado no te
impide usar sus imágenes.</p>
<p>Imágenes y contenedores viven en tu carpeta personal
(<code>~/.local/share/containers/storage</code>), no en <code>/var/lib</code>. Cada usuario tiene los
suyos y no se ven entre sí.</p>
<h2 id="los-tres-sitios-donde-rootless-te-muerde">Los tres sitios donde rootless te muerde <a class="ancla" href="#los-tres-sitios-donde-rootless-te-muerde" aria-label="Enlace a esta sección">#</a></h2>
<h3 id="1-permisos-de-los-volúmenes">1. Permisos de los volúmenes <a class="ancla" href="#1-permisos-de-los-vol%c3%bamenes" aria-label="Enlace a esta sección">#</a></h3>
<p>Es el problema número uno: montas una carpeta tuya dentro del contenedor y el
programa de dentro no puede escribir, o escribe pero los ficheros te aparecen con
un dueño imposible.</p>
<p>Lo he montado como demostración en el laboratorio, <code>permisos/demo.sh</code>. Una
imagen mínima (sin descargar nada) cuyo proceso corre como <strong>UID 1000 dentro del
contenedor</strong>, como harían muchas imágenes reales que declaran un <code>USER</code> sin
privilegios, e intenta crear un fichero en una carpeta tuya. Aquí mi usuario es el
30033, no el 1000. Lo que pasa:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#f92672">===</span> A<span style="color:#f92672">)</span> Sin opciones: el UID <span style="color:#ae81ff">1000</span> de dentro no es tu usuario de fuera
</span></span><span style="display:flex;"><span>dentro: uid<span style="color:#f92672">=</span><span style="color:#ae81ff">1000</span> gid<span style="color:#f92672">=</span><span style="color:#ae81ff">0</span>
</span></span><span style="display:flex;"><span>no puedo escribir en /datos: Permission denied</span></span></code></pre></div>
</div>
<p>Con la fórmula de antes: el UID 1000 de dentro es el 166535 de fuera, que no es
el dueño de la carpeta (30033) ni tiene permisos sobre ella. Lógico.</p>
<p>La primera idea es probar <code>--userns=keep-id</code>, que conserva tu UID dentro del
contenedor. Y <strong>no funciona</strong>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#f92672">===</span> B<span style="color:#f92672">)</span> --userns<span style="color:#f92672">=</span>keep-id: tu UID se conserva, pero el proceso sigue siendo el <span style="color:#ae81ff">1000</span>
</span></span><span style="display:flex;"><span>dentro: uid<span style="color:#f92672">=</span><span style="color:#ae81ff">1000</span> gid<span style="color:#f92672">=</span><span style="color:#ae81ff">0</span>
</span></span><span style="display:flex;"><span>no puedo escribir en /datos: Permission denied</span></span></code></pre></div>
</div>
<p><code>keep-id</code> hace que <em>tu</em> UID de fuera (30033) sea el mismo dentro. Pero el
proceso corre como el 1000 por el <code>USER</code> de la imagen, que ya no coincide con
nadie. Lo que necesitas es decirle a Podman que <strong>el 1000 de dentro seas tú</strong>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#f92672">===</span> C<span style="color:#f92672">)</span> --userns<span style="color:#f92672">=</span>keep-id:uid<span style="color:#f92672">=</span>1000,gid<span style="color:#f92672">=</span>1000: el <span style="color:#ae81ff">1000</span> de dentro eres TÚ de fuera
</span></span><span style="display:flex;"><span>dentro: uid<span style="color:#f92672">=</span><span style="color:#ae81ff">1000</span> gid<span style="color:#f92672">=</span><span style="color:#ae81ff">0</span>
</span></span><span style="display:flex;"><span>escrito /datos/creado-por-contenedor.txt
</span></span><span style="display:flex;"><span>en el disco <span style="color:#f92672">(</span>uid:gid numéricos<span style="color:#f92672">)</span>:
</span></span><span style="display:flex;"><span>-rw-r--r-- <span style="color:#ae81ff">1</span> <span style="color:#ae81ff">30033</span> <span style="color:#ae81ff">165536</span> <span style="color:#ae81ff">5</span> Nov  <span style="color:#ae81ff">4</span> 20:27 creado-por-contenedor.txt</span></span></code></pre></div>
</div>
<p>El proceso es el 1000 de dentro, el fichero aparece en el disco con tu UID de
fuera, y puedes editarlo y borrarlo sin problemas. En Quadlet se escribe
<code>UserNS=keep-id:uid=1000,gid=1000</code>.</p>
<p>La alternativa es no tocar el mapa y cambiar el dueño de la carpeta para que
coincida con lo que verá el contenedor. Desde fuera no puedes hacer <code>chown</code> a un
UID subordinado, pero <code>podman unshare</code> te mete en el espacio de usuarios de
Podman, y desde ahí sí:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#f92672">===</span> D<span style="color:#f92672">)</span> Sin keep-id, pero con la carpeta dada al UID <span style="color:#ae81ff">1000</span> *de dentro*
</span></span><span style="display:flex;"><span>carpeta vista desde fuera:
</span></span><span style="display:flex;"><span>drwxr-xr-x <span style="color:#ae81ff">2</span> <span style="color:#ae81ff">166535</span> <span style="color:#ae81ff">166535</span> <span style="color:#ae81ff">4096</span> Nov  <span style="color:#ae81ff">4</span> 20:27 /tmp/tmp.qCpiztyWeY/datos
</span></span><span style="display:flex;"><span>dentro: uid<span style="color:#f92672">=</span><span style="color:#ae81ff">1000</span> gid<span style="color:#f92672">=</span><span style="color:#ae81ff">0</span>
</span></span><span style="display:flex;"><span>escrito /datos/creado-por-contenedor.txt
</span></span><span style="display:flex;"><span>en el disco <span style="color:#f92672">(</span>uid:gid numéricos<span style="color:#f92672">)</span>:
</span></span><span style="display:flex;"><span>-rw-r--r-- <span style="color:#ae81ff">1</span> <span style="color:#ae81ff">166535</span> <span style="color:#ae81ff">30033</span> <span style="color:#ae81ff">5</span> Nov  <span style="color:#ae81ff">4</span> 20:27 creado-por-contenedor.txt</span></span></code></pre></div>
</div>
<p>Funciona, pero ahora la carpeta (y lo que se cree dentro) es del 166535 y ya no
es tuya: para tocarla tú tendrás que entrar con <code>podman unshare</code> también. Es la
solución adecuada para datos que sólo debe tocar el contenedor; para una carpeta
de trabajo tuya, <code>keep-id:uid=...</code> es mejor.</p>
<p>Tres matices:</p>
<ul>
<li><strong>Si la imagen corre como root</strong>, que es lo que hacen muchas al arrancar, no
tienes este problema: el root de dentro eres tú.</li>
<li><strong>Los volúmenes con nombre</strong> (<code>podman volume create</code>, o <code>.volume</code> en Quadlet)
los gestiona Podman y normalmente no dan este problema, así que son la opción
cómoda para datos que no necesitas tocar a mano.</li>
<li><strong>En Ubuntu las carpetas nuevas suelen salir con modo 775</strong> y el <code>gid</code> 0 del
contenedor se corresponde con tu grupo, así que a veces el contenedor <em>sí</em>
consigue escribir «de rebote» por el permiso de grupo. En la demo creo la
carpeta con modo 755 a propósito para ver el problema limpio. Aun así, lo que
escriba así aparecerá con un dueño raro (en mis pruebas, <code>166535:30033</code>).</li>
</ul>
<p>Y una nota para quien venga de Fedora o Red Hat: allí los volúmenes suelen
llevar <code>:Z</code> por SELinux. En Ubuntu la seguridad la lleva AppArmor y
normalmente no hace falta.</p>
<h3 id="2-puertos-por-debajo-del-1024">2. Puertos por debajo del 1024 <a class="ancla" href="#2-puertos-por-debajo-del-1024" aria-label="Enlace a esta sección">#</a></h3>
<p>Un usuario sin privilegios no puede abrir puertos bajos, incluidos el 80 y el
443. En muchas distribuciones el umbral por defecto es el 1024; compruébalo:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ sysctl net.ipv4.ip_unprivileged_port_start</span></span></code></pre></div>
</div>
<p>Lo más sencillo es publicar un puerto alto (<code>8080</code>) y que lo atienda un proxy
inverso o una redirección del cortafuegos. Bajar el umbral con sysctl también
funciona, pero es una decisión de root que afecta a todo el sistema.</p>
<p>Una buena costumbre: publica en <code>127.0.0.1</code> si sólo quieres acceder tú.
<code>-p 8080:8080</code> abre el puerto en <strong>todas</strong> las interfaces; <code>-p 127.0.0.1:8080:8080</code> sólo en local.</p>
<h3 id="3-la-red">3. La red <a class="ancla" href="#3-la-red" aria-label="Enlace a esta sección">#</a></h3>
<p>Un contenedor rootless no puede crear interfaces de red de verdad, así que usa
un traductor en espacio de usuario. En Podman 5 el predeterminado es <strong>pasta</strong>
(antes era <code>slirp4netns</code>). Para el uso cotidiano es transparente: salen a
internet y publican puertos sin más. Donde se nota es en redes muy exigentes y en
detalles como la IP de origen de las conexiones entrantes, que puede aparecer
distinta de la real.</p>
<p>Otra diferencia entre versiones: Podman 5 usa siempre <em>netavark</em> para las redes
entre contenedores; en Podman 4 podía ser CNI (es lo que usa mi entorno de
pruebas).</p>
<h2 id="el-problema-podman-run-no-sobrevive-a-un-reinicio">El problema: <code>podman run</code> no sobrevive a un reinicio <a class="ancla" href="#el-problema-podman-run-no-sobrevive-a-un-reinicio" aria-label="Enlace a esta sección">#</a></h2>
<p>Con todo lo anterior, esto funciona:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ podman run -d --name lab-db --network lab <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>    -v lab-datos:/var/lib/postgresql/data <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>    --env-file ~/.config/lab-podman/db.env <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>    -e POSTGRES_USER<span style="color:#f92672">=</span>lab -e POSTGRES_DB<span style="color:#f92672">=</span>lab <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>    docker.io/library/postgres:16</span></span></code></pre></div>
</div>
<p>Y ahora la parte incómoda: ese comando vive en tu historial. Si reinicias, el
contenedor no vuelve. Si lo recreas, tienes que acordarte de todas las opciones.
Podman tiene <code>--restart=always</code>, pero por sí solo no basta en rootless: sin nada
que arranque Podman al iniciar el sistema, no hay quien reinicie nada. El
mecanismo adecuado es systemd, y la forma moderna de conectarlo con Podman se
llama <strong>Quadlet</strong>. (<code>podman generate systemd</code> fabrica unidades a partir de un
contenedor ya creado, pero está marcado como obsoleto a favor de Quadlet.)</p>
<h2 id="quadlet-describe-el-contenedor-en-un-fichero">Quadlet: describe el contenedor en un fichero <a class="ancla" href="#quadlet-describe-el-contenedor-en-un-fichero" aria-label="Enlace a esta sección">#</a></h2>
<p>La idea es simple: en vez de un comando imperativo, escribes un fichero
declarativo y systemd se encarga del resto. Un generador de Podman lee tus
ficheros y fabrica las unidades de servicio al vuelo. Para tu usuario, los
ficheros van en <code>~/.config/containers/systemd/</code> (la
<a href="https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html" target="_blank" rel="noopener">documentación</a>
lista más rutas; por ejemplo, lo que pongas en <code>/etc/containers/systemd/users/</code>
se ejecuta cuando cualquier usuario inicia sesión). Hay un tipo de fichero por
cosa:</p>
<table>
  <thead>
      <tr>
          <th>Extensión</th>
          <th>Qué describe</th>
          <th>Servicio generado</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>.container</code></td>
          <td>un contenedor</td>
          <td><code>nombre.service</code></td>
      </tr>
      <tr>
          <td><code>.volume</code></td>
          <td>un volumen con nombre</td>
          <td><code>nombre-volume.service</code></td>
      </tr>
      <tr>
          <td><code>.network</code></td>
          <td>una red</td>
          <td><code>nombre-network.service</code></td>
      </tr>
  </tbody>
</table>
<p>Según la versión de Podman hay más tipos (<code>.pod</code>, <code>.kube</code>, <code>.build</code>&hellip;); mira la
documentación de la tuya.</p>
<p>El laboratorio monta un servicio típico: <strong>PostgreSQL con su volumen, en una red
propia, y una interfaz web (Adminer) que habla con él</strong>. Son cuatro ficheros
pequeños.</p>
<p>La red, <code>lab.network</code>, y el volumen, <code>lab-datos.volume</code>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#66d9ef">[Network]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">NetworkName</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab</span></span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#66d9ef">[Volume]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">VolumeName</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab-datos</span></span></span></code></pre></div>
</div>
<p>La base de datos, <code>lab-db.container</code>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#66d9ef">[Unit]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Description</span><span style="color:#f92672">=</span><span style="color:#e6db74">PostgreSQL del laboratorio (Podman rootless)</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">[Container]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">ContainerName</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab-db</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Image</span><span style="color:#f92672">=</span><span style="color:#e6db74">docker.io/library/postgres:16</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Network</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab.network</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Volume</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab-datos.volume:/var/lib/postgresql/data</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">EnvironmentFile</span><span style="color:#f92672">=</span><span style="color:#e6db74">%h/.config/lab-podman/db.env</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Environment</span><span style="color:#f92672">=</span><span style="color:#e6db74">POSTGRES_USER=lab</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Environment</span><span style="color:#f92672">=</span><span style="color:#e6db74">POSTGRES_DB=lab</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">HealthCmd</span><span style="color:#f92672">=</span><span style="color:#e6db74">pg_isready -U lab -d lab</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">HealthInterval</span><span style="color:#f92672">=</span><span style="color:#e6db74">10s</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">HealthRetries</span><span style="color:#f92672">=</span><span style="color:#e6db74">5</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">[Service]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Restart</span><span style="color:#f92672">=</span><span style="color:#e6db74">always</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">TimeoutStartSec</span><span style="color:#f92672">=</span><span style="color:#e6db74">300</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">[Install]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">WantedBy</span><span style="color:#f92672">=</span><span style="color:#e6db74">default.target</span></span></span></code></pre></div>
</div>
<p>Y la interfaz web, <code>lab-adminer.container</code>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ini" data-lang="ini"><span style="display:flex;"><span><span style="color:#66d9ef">[Unit]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Description</span><span style="color:#f92672">=</span><span style="color:#e6db74">Adminer: interfaz web para la base de datos del laboratorio</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Requires</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab-db.service</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">After</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab-db.service</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">[Container]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">ContainerName</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab-adminer</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Image</span><span style="color:#f92672">=</span><span style="color:#e6db74">docker.io/library/adminer:latest</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Network</span><span style="color:#f92672">=</span><span style="color:#e6db74">lab.network</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">PublishPort</span><span style="color:#f92672">=</span><span style="color:#e6db74">127.0.0.1:8080:8080</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Environment</span><span style="color:#f92672">=</span><span style="color:#e6db74">ADMINER_DEFAULT_SERVER=lab-db</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">AutoUpdate</span><span style="color:#f92672">=</span><span style="color:#e6db74">registry</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">[Service]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">Restart</span><span style="color:#f92672">=</span><span style="color:#e6db74">always</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">[Install]</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">WantedBy</span><span style="color:#f92672">=</span><span style="color:#e6db74">default.target</span></span></span></code></pre></div>
</div>
<p>Qué hace cada pieza:</p>
<ul>
<li><strong><code>Network=lab.network</code></strong> y <strong><code>Volume=lab-datos.volume:...</code></strong>: en vez de un
nombre, apuntan a las unidades <code>.network</code> y <code>.volume</code>. Quadlet añade solo las
dependencias: antes de arrancar el contenedor se crean la red y el volumen.</li>
<li><strong>Sin <code>PublishPort</code> en la base de datos</strong>: no es accesible desde fuera. Sólo
Adminer, que está en la misma red, la ve, y la encuentra por el nombre del
contenedor (<code>lab-db</code>).</li>
<li><strong><code>EnvironmentFile=%h/...</code></strong>: la contraseña de la base de datos no está en el
fichero Quadlet (para poder versionarlo sin filtrarla) sino en un fichero
aparte con modo 600. El <code>%h</code> es el <em>specifier</em> de systemd para tu carpeta
personal.</li>
<li><strong><code>HealthCmd</code> y compañía</strong>: un chequeo de salud, para que <code>podman ps</code> y
systemd sepan si la base de datos responde y no sólo si el proceso existe.</li>
<li><strong>La etiqueta <code>postgres:16</code> fija</strong> y <strong><code>AutoUpdate=registry</code></strong> en Adminer: una
base de datos no debería actualizarse sola, una interfaz web sí puede. Hablo de
esto más abajo.</li>
<li><strong><code>[Service]</code></strong> y <strong><code>[Install]</code></strong>: son secciones normales de systemd. Con
<code>WantedBy=default.target</code> se arranca con la sesión de usuario; es lo que haría
<code>systemctl enable</code>, que con Quadlet no puedes ejecutar porque las unidades
generadas son transitorias.</li>
</ul>
<h3 id="qué-fabrica-quadlet-por-debajo">Qué fabrica Quadlet por debajo <a class="ancla" href="#qu%c3%a9-fabrica-quadlet-por-debajo" aria-label="Enlace a esta sección">#</a></h3>
<p>No es magia: traduce tus ficheros a unidades de systemd normales cuyo
<code>ExecStart</code> es un <code>podman run</code>. Puedes verlo sin instalar nada con el modo
<code>--dryrun</code> del generador. Este es el extracto de la base de datos, tal cual lo
generó Podman 4.9.3 en mis pruebas:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>ExecStart=/usr/bin/podman run --name=lab-db --cidfile=%t/%N.cid --replace --rm
</span></span><span style="display:flex;"><span>  --cgroups=split --network=lab --sdnotify=conmon -d -v lab-datos:/var/lib/postgresql/data
</span></span><span style="display:flex;"><span>  --env POSTGRES_DB=lab --env POSTGRES_USER=lab --env-file %h/.config/lab-podman/db.env
</span></span><span style="display:flex;"><span>  --health-cmd &#34;pg_isready -U lab -d lab&#34; --health-interval 10s --health-retries 5
</span></span><span style="display:flex;"><span>  docker.io/library/postgres:16</span></span></code></pre></div>
</div>
<p>(Lo he partido en varias líneas para que se lea; en la salida original es una
sola línea.) Es tu <code>podman run</code> de antes, pero generado desde un fichero
declarativo, con <code>--replace</code>, <code>--rm</code> y la integración con systemd añadidas. También
genera <code>Requires=</code> y <code>After=</code> hacia la red y el volumen, que es de donde sale el
orden de arranque.</p>
<h3 id="validar-cargar-y-arrancar">Validar, cargar y arrancar <a class="ancla" href="#validar-cargar-y-arrancar" aria-label="Enlace a esta sección">#</a></h3>
<p>El laboratorio trae <code>instalar.sh</code>, que hace los pasos en orden y no usa <code>sudo</code>:
valida con Quadlet, crea la contraseña aleatoria en <code>~/.config/lab-podman/db.env</code>
con modo 600, copia los ficheros a <code>~/.config/containers/systemd/</code>, recarga
systemd y arranca los servicios. Sin ejecutarlo, puedes sólo validar:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~/lab-podman$ ./instalar.sh --solo-validar
</span></span><span style="display:flex;"><span>&gt;&gt; Validando los ficheros Quadlet con /usr/lib/systemd/system-generators/podman-system-generator
</span></span><span style="display:flex;"><span>   Válidos: <span style="color:#ae81ff">4</span> fichero<span style="color:#f92672">(</span>s<span style="color:#f92672">)</span>.</span></span></code></pre></div>
</div>
<p>Los pasos manuales, para que veas qué hay detrás. Todo es <code>--user</code>: son servicios
de tu usuario, no del sistema.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
</span></span><span style="display:flex;"><span>usuario@equipo:~$ systemctl --user daemon-reload
</span></span><span style="display:flex;"><span>usuario@equipo:~$ systemctl --user start lab-db.service lab-adminer.service
</span></span><span style="display:flex;"><span>usuario@equipo:~$ systemctl --user status lab-db.service</span></span></code></pre></div>
</div>
<p>Los ficheros Quadlet se leen al arrancar y en cada <code>daemon-reload</code>: cada vez que
edites uno, repite el <code>daemon-reload</code> y reinicia el servicio. Los logs están en
el journal:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ journalctl --user -u lab-db.service -f</span></span></code></pre></div>
</div>
<p>(Si no ves nada, comprueba que el journal sea persistente y que tu usuario pueda
leerlo.) También tienes <code>podman ps</code> y <code>podman logs lab-db</code>; los contenedores se
llaman <code>lab-db</code> y <code>lab-adminer</code> por el <code>ContainerName=</code> (por defecto serían
<code>systemd-lab-db</code>&hellip;). Pero la fuente de verdad pasa a ser systemd.</p>
<h2 id="que-arranque-solo-al-iniciar-el-equipo-linger">Que arranque solo al iniciar el equipo: linger <a class="ancla" href="#que-arranque-solo-al-iniciar-el-equipo-linger" aria-label="Enlace a esta sección">#</a></h2>
<p>El segundo tropiezo clásico. Los servicios de usuario viven mientras tu sesión
está abierta: si reinicias y no inicias sesión, el contenedor no arranca, y si
cierras la última sesión, se para. Para que los servicios de tu usuario arranquen
con la máquina, sin sesión, se activa el <em>linger</em>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ loginctl enable-linger usuario
</span></span><span style="display:flex;"><span>usuario@equipo:~$ loginctl show-user usuario --property<span style="color:#f92672">=</span>Linger
</span></span><span style="display:flex;"><span>Linger<span style="color:#f92672">=</span>yes</span></span></code></pre></div>
</div>
<p>Según cómo esté configurado polkit, puede pedirte autenticarte. Con linger y el
<code>[Install]</code> de los ficheros, los servicios vuelven solos tras cada reinicio.</p>
<h2 id="actualizaciones-automáticas">Actualizaciones automáticas <a class="ancla" href="#actualizaciones-autom%c3%a1ticas" aria-label="Enlace a esta sección">#</a></h2>
<p><code>AutoUpdate=registry</code> marca el contenedor para que Podman compruebe si hay una
imagen nueva en el registro. Requiere un nombre de imagen <strong>completo</strong>, porque
Podman necesita saber de dónde descargarla. También existe <code>AutoUpdate=local</code>,
que compara con la copia local. Las comprobaciones las lanza un temporizador que
trae Podman:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>usuario@equipo:~$ podman auto-update --dry-run
</span></span><span style="display:flex;"><span>usuario@equipo:~$ systemctl --user enable --now podman-auto-update.timer</span></span></code></pre></div>
</div>
<p>El primero te dice qué se actualizaría sin tocar nada; el segundo programa la
comprobación periódica. Cuando hay una imagen nueva, Podman la descarga y
reinicia el servicio.</p>
<p>Actualizar solo es cómodo y arriesgado a la vez. Por eso en el laboratorio sólo
Adminer lo lleva: para una interfaz web no pasa nada. Para algo con datos, mejor
fijar una etiqueta de versión (<code>postgres:16</code>) y actualizar a mano, leyendo antes
las notas de versión.</p>
<h2 id="cuando-algo-no-va-chuleta-de-diagnóstico">Cuando algo no va: chuleta de diagnóstico <a class="ancla" href="#cuando-algo-no-va-chuleta-de-diagn%c3%b3stico" aria-label="Enlace a esta sección">#</a></h2>
<table>
  <thead>
      <tr>
          <th>Síntoma</th>
          <th>Qué mirar</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>Failed to connect to bus</code> con <code>systemctl --user</code></td>
          <td>Sesión sin <code>XDG_RUNTIME_DIR</code> (típico tras <code>su</code> o <code>sudo -u</code>). Usa un login real o <code>machinectl shell usuario@</code>.</td>
      </tr>
      <tr>
          <td>El servicio no aparece tras crear el fichero</td>
          <td><code>daemon-reload</code>, y luego el <code>--dryrun</code> del generador para ver errores de sintaxis.</td>
      </tr>
      <tr>
          <td>«Permission denied» al escribir en un volumen</td>
          <td>El mapa de UIDs: <code>UserNS=keep-id:uid=...,gid=...</code> o <code>podman unshare chown</code>.</td>
      </tr>
      <tr>
          <td>No arranca tras reiniciar</td>
          <td>¿Linger activado? ¿Tiene <code>[Install]</code>?</td>
      </tr>
      <tr>
          <td>El puerto no responde</td>
          <td><code>podman ps</code>; ¿puerto &lt; 1024?; ¿publicas en <code>127.0.0.1</code> y accedes desde otra máquina?</td>
      </tr>
      <tr>
          <td>Un contenedor no encuentra a otro por nombre</td>
          <td>¿Están en la misma red (<code>Network=</code>)? ¿Usas el <code>ContainerName=</code>?</td>
      </tr>
      <tr>
          <td>Falla al descargar la imagen</td>
          <td>Nombre completo con registro; <code>podman pull</code> a mano para ver el error real.</td>
      </tr>
      <tr>
          <td>Se llena el disco</td>
          <td><code>podman system df</code> para ver el uso y <code>podman system prune</code> para limpiar lo que no se usa.</td>
      </tr>
  </tbody>
</table>
<h2 id="qué-sí-necesita-root-una-vez">Qué sí necesita root (una vez) <a class="ancla" href="#qu%c3%a9-s%c3%ad-necesita-root-una-vez" aria-label="Enlace a esta sección">#</a></h2>
<p>Rootless no significa que no necesites privilegios nunca, sino que los necesitas
<strong>al preparar la máquina</strong> y no para ejecutar cosas:</p>
<table>
  <thead>
      <tr>
          <th>Tarea</th>
          <th>¿Root?</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Instalar <code>podman</code> y <code>uidmap</code></td>
          <td>Sí, una vez</td>
      </tr>
      <tr>
          <td>Rangos en <code>/etc/subuid</code> y <code>/etc/subgid</code></td>
          <td>Sí, una vez (normalmente ya vienen)</td>
      </tr>
      <tr>
          <td>Bajar el umbral de puertos con sysctl</td>
          <td>Sí, y es opcional</td>
      </tr>
      <tr>
          <td><code>loginctl enable-linger</code></td>
          <td>Según polkit</td>
      </tr>
      <tr>
          <td>Descargar imágenes, crear contenedores, servicios Quadlet</td>
          <td>No</td>
      </tr>
  </tbody>
</table>
<h2 id="el-laboratorio-y-lo-que-he-probado">El laboratorio y lo que he probado <a class="ancla" href="#el-laboratorio-y-lo-que-he-probado" aria-label="Enlace a esta sección">#</a></h2>
<p>Está en la carpeta
<a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-podman" target="_blank" rel="noopener"><code>lab-podman/</code></a>
del repositorio de laboratorios. Los scripts son <code>./comprobar.sh</code> (diagnóstico),
<code>./instalar.sh</code> (con <code>--solo-validar</code> para no tocar nada) y <code>./desinstalar.sh</code>
(con <code>--purgar</code> para borrar también los datos), más <code>permisos/demo.sh</code> para la
demostración de UIDs.</p>
<p>Para ser claro con lo que está comprobado y lo que no:</p>
<ul>
<li><strong>Probado</strong> (Ubuntu 24.04, Podman 4.9.3, usuario sin privilegios): la demo de
permisos de principio a fin, el diagnóstico, y que el generador de Quadlet
acepta los cuatro ficheros y produce las unidades que he enseñado.</li>
<li><strong>No probado</strong>: el arranque real de los servicios (<code>systemctl --user start</code>,
la descarga de las imágenes y la conexión de Adminer a PostgreSQL), porque mi
entorno de pruebas no tenía sesión de systemd de usuario ni acceso a los
registros. Si lo ejecutas y algo falla, el <code>journalctl --user</code> te dirá qué.</li>
<li><strong>Versiones</strong>: las salidas son de Podman 4.9.3. En Podman 5 cambian cosas
(la red por defecto, el backend netavark, tipos nuevos de unidad), pero los
conceptos y los ficheros de esta entrada son los mismos.</li>
</ul>
<h2 id="para-quedarte-con-algo">Para quedarte con algo <a class="ancla" href="#para-quedarte-con-algo" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li>Rootless = sin demonio y sin root: el <code>root</code> del contenedor eres tú, y los
demás UIDs de dentro son un rango subordinado: el UID <code>N</code> de dentro es el
<code>165535 + N</code> de fuera, con los números de tu <code>/etc/subuid</code>.</li>
<li>Casi todos los problemas de permisos son ese mapa. <code>--userns=keep-id</code> sólo no
basta si el <code>USER</code> de la imagen no es tu UID: usa <code>keep-id:uid=...,gid=...</code>, o
<code>podman unshare chown</code>, o un volumen con nombre.</li>
<li>Un <code>podman run</code> que no está escrito en un fichero es un contenedor que acabarás
perdiendo. Quadlet convierte la configuración en ficheros que puedes versionar.</li>
<li><code>daemon-reload</code> tras cada cambio, <code>--dryrun</code> para validar y <code>linger</code> para que
arranque con la máquina.</li>
<li>Guarda los ficheros de <code>~/.config/containers/systemd/</code> en un repositorio.</li>
</ul>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_a48aaae836eeb9d0.png"/></item><item><title>EXPLAIN ANALYZE para humanos: leer un plan de PostgreSQL sin sufrir</title><link>https://www.igalvan.es/posts/2026/explain-analyze-para-humanos/</link><pubDate>Wed, 04 Nov 2026 19:30:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/explain-analyze-para-humanos/</guid><description><![CDATA[<p>Hay una pregunta que todos hemos hecho alguna vez, normalmente con cara de
funeral: <em>«el índice existe, ¿por qué PostgreSQL pasa de él?»</em>.</p>
<p>Mira estas dos consultas sobre la misma tabla de un millón de filas. Devuelven
exactamente las mismas 726 filas:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>-- Consulta A
</span></span><span style="display:flex;"><span>Seq Scan on pedidos  (cost=0.00..24853.00 rows=5000 width=27) (actual time=0.104..459.164 rows=726 loops=1)
</span></span><span style="display:flex;"><span>Execution Time: 459.294 ms
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>-- Consulta B
</span></span><span style="display:flex;"><span>Bitmap Heap Scan on pedidos  (cost=9.94..2118.47 rows=712 width=27) (actual time=0.235..1.202 rows=726 loops=1)
</span></span><span style="display:flex;"><span>Execution Time: 1.272 ms</span></span></code></pre></div>
</div>
<p>459 milisegundos frente a 1,2. La diferencia entre una y otra es una sola
línea de SQL, y está justo ahí, en el plan. Al final de la entrada vuelvo a
ellas. Antes toca aprender a leer lo que PostgreSQL nos cuenta, que parece un
volcado ilegible pero se lee con cuatro reglas.</p>
<p>Todo lo que ves aquí sale de un laboratorio que puedes reproducir en tu
máquina. Las salidas están capturadas con <strong>PostgreSQL 16.15</strong>; más abajo
cuento qué cambia en versiones más nuevas.</p>
<h2 id="el-laboratorio">El laboratorio <a class="ancla" href="#el-laboratorio" aria-label="Enlace a esta sección">#</a></h2>
<p>Tres tablas sintéticas, generadas con <code>generate_series()</code> y <code>random()</code>, para no
descargar nada:</p>
<table>
  <thead>
      <tr>
          <th>Tabla</th>
          <th>Filas</th>
          <th>Tamaño total</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>clientes</code></td>
          <td>10 000</td>
          <td>1,3 MB</td>
      </tr>
      <tr>
          <td><code>pedidos</code></td>
          <td>1 000 000</td>
          <td>79 MB</td>
      </tr>
      <tr>
          <td><code>lineas_pedido</code></td>
          <td>3 000 000</td>
          <td>261 MB</td>
      </tr>
  </tbody>
</table>
<p>Cada pedido tiene exactamente 3 líneas y cada cliente unos 100 pedidos. El 90 %
de los pedidos están en estado <code>entregado</code> y sólo el 0,5 % en <code>devuelto</code>; lo
usaremos a propósito. Además, <code>provincia</code>, <code>municipio</code> y <code>codigo_postal</code> de los
clientes están fuertemente correlacionados, y eso también tiene su historia.</p>
<p>El código está en el repositorio público de laboratorios, en la carpeta
<a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-explain" target="_blank" rel="noopener"><code>lab-explain/</code></a>,
autosuficiente como las de las otras series. Con Podman:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>ignacio@zeus:~$ git clone https://codeberg.org/igalvan/blog-public-code.git
</span></span><span style="display:flex;"><span>ignacio@zeus:~$ cd blog-public-code/lab-explain
</span></span><span style="display:flex;"><span>ignacio@zeus:~/blog-public-code/lab-explain$ ./lab.sh up      # PostgreSQL en un contenedor
</span></span><span style="display:flex;"><span>ignacio@zeus:~/blog-public-code/lab-explain$ ./lab.sh init    # crea y carga las tablas (~20 s)
</span></span><span style="display:flex;"><span>ignacio@zeus:~/blog-public-code/lab-explain$ ./lab.sh run      # ejecuta las consultas
</span></span></code></pre></div>
</div>
<p><code>./lab.sh run</code> guarda cada salida en <code>salidas/</code>. Si prefieres usar un
PostgreSQL que ya tengas instalado, basta con definir <code>PSQL_CMD</code> (el README lo
explica).</p>
<p>Una decisión de laboratorio: todas las consultas empiezan con
<code>SET max_parallel_workers_per_gather = 0;</code> y <code>SET jit = off;</code>. El paralelismo
añade nodos <code>Gather</code> y <code>Workers</code> que son muy interesantes, pero estorban cuando
estás aprendiendo a leer. En producción lo normal es tenerlos activados.</p>
<h2 id="explain-y-explain-analyze-no-son-lo-mismo">EXPLAIN y EXPLAIN ANALYZE no son lo mismo <a class="ancla" href="#explain-y-explain-analyze-no-son-lo-mismo" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li><code>EXPLAIN consulta</code> <strong>estima</strong>: muestra el plan que PostgreSQL elegiría y lo
que <em>cree</em> que va a costar, sin ejecutar nada.</li>
<li><code>EXPLAIN ANALYZE consulta</code> <strong>ejecuta de verdad</strong> la consulta y añade lo que
pasó realmente: tiempos y filas reales.</li>
<li><code>EXPLAIN (ANALYZE, BUFFERS) consulta</code> añade cuántas páginas de memoria o disco
tocó cada nodo. Es la forma que uso casi siempre.</li>
</ul>
<p>Un aviso que conviene tatuarse: como <code>ANALYZE</code> ejecuta la consulta, con un
<code>UPDATE</code>, <code>DELETE</code> o <code>INSERT</code> <strong>modifica los datos</strong>. Si quieres ver el plan sin
consecuencias:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#66d9ef">BEGIN</span>;
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">EXPLAIN</span> (<span style="color:#66d9ef">ANALYZE</span>, BUFFERS) <span style="color:#66d9ef">UPDATE</span> pedidos <span style="color:#66d9ef">SET</span> estado <span style="color:#f92672">=</span> <span style="color:#e6db74">&#39;enviado&#39;</span> <span style="color:#66d9ef">WHERE</span> id <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span>;
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">ROLLBACK</span>;</span></span></code></pre></div>
</div>
<h2 id="regla-1-el-plan-es-un-árbol-y-se-lee-de-dentro-hacia-fuera">Regla 1: el plan es un árbol y se lee de dentro hacia fuera <a class="ancla" href="#regla-1-el-plan-es-un-%c3%a1rbol-y-se-lee-de-dentro-hacia-fuera" aria-label="Enlace a esta sección">#</a></h2>
<p>Cada línea con <code>-&gt;</code> es un <strong>nodo</strong>. Los nodos más indentados se ejecutan
primero y pasan sus filas al nodo de encima. Este es el plan de una unión
sencilla, recortado:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Nested Loop  (cost=5.49..380.77 rows=100 width=22) (actual time=0.075..0.299 rows=103 loops=1)
</span></span><span style="display:flex;"><span>  -&gt;  Index Scan using clientes_pkey on clientes c  (cost=0.29..8.30 rows=1 width=16) (actual time=0.026..0.027 rows=1 loops=1)
</span></span><span style="display:flex;"><span>        Index Cond: (id = 4242)
</span></span><span style="display:flex;"><span>  -&gt;  Bitmap Heap Scan on pedidos p  (cost=5.20..371.46 rows=100 width=14) (actual time=0.043..0.254 rows=103 loops=1)
</span></span><span style="display:flex;"><span>        Recheck Cond: (cliente_id = 4242)
</span></span><span style="display:flex;"><span>        -&gt;  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.17 rows=100 width=0) (actual time=0.024..0.024 rows=103 loops=1)
</span></span><span style="display:flex;"><span>              Index Cond: (cliente_id = 4242)
</span></span><span style="display:flex;"><span>Execution Time: 0.400 ms</span></span></code></pre></div>
</div>
<p>Primero se busca el cliente por clave primaria, luego se buscan sus pedidos
con el índice de <code>cliente_id</code>, y arriba el <code>Nested Loop</code> los combina.</p>
<p>Y cada nodo trae dos paréntesis con casi el mismo formato:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>(cost=5.20..371.46 rows=100 width=14)              &lt;- lo que PostgreSQL ESTIMA
</span></span><span style="display:flex;"><span>(actual time=0.043..0.254 rows=103 loops=1)        &lt;- lo que PASÓ DE VERDAD</span></span></code></pre></div>
</div>
<ul>
<li><strong><code>cost=arranque..total</code></strong>: coste estimado en unidades arbitrarias. El primer
número es lo que cuesta producir la primera fila; el segundo, la última. No
son milisegundos: es una moneda interna que sirve para comparar planes.</li>
<li><strong><code>rows</code></strong>: filas que se estiman (o que salieron de verdad, en el segundo
paréntesis).</li>
<li><strong><code>width</code></strong>: ancho medio de la fila, en bytes.</li>
<li><strong><code>actual time=arranque..total</code></strong>: milisegundos reales, <strong>por cada vuelta</strong>.</li>
<li><strong><code>loops</code></strong>: cuántas veces se ejecutó este nodo.</li>
</ul>
<p>Esa última pareja es la trampa más habitual y nos lleva a la regla 2.</p>
<h2 id="regla-2-el-tiempo-real-es-por-vuelta-multiplica-por-loops">Regla 2: el tiempo real es por vuelta, multiplica por <code>loops</code> <a class="ancla" href="#regla-2-el-tiempo-real-es-por-vuelta-multiplica-por-loops" aria-label="Enlace a esta sección">#</a></h2>
<p>Esta unión devuelve los pedidos de todos los clientes de un municipio:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Nested Loop  (cost=5.13..15440.31 rows=5400 width=22) (actual time=0.070..29.251 rows=5425 loops=1)
</span></span><span style="display:flex;"><span>  -&gt;  Seq Scan on clientes c  (cost=0.00..259.00 rows=54 width=16) (actual time=0.027..1.476 rows=54 loops=1)
</span></span><span style="display:flex;"><span>        Filter: (municipio = &#39;Municipio 7&#39;::text)
</span></span><span style="display:flex;"><span>        Rows Removed by Filter: 9946
</span></span><span style="display:flex;"><span>  -&gt;  Bitmap Heap Scan on pedidos p  (cost=5.13..280.13 rows=101 width=14) (actual time=0.026..0.496 rows=100 loops=54)
</span></span><span style="display:flex;"><span>        Recheck Cond: (c.id = cliente_id)
</span></span><span style="display:flex;"><span>        -&gt;  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.11 rows=101 width=0) (actual time=0.011..0.011 rows=100 loops=54)
</span></span><span style="display:flex;"><span>              Index Cond: (cliente_id = c.id)
</span></span><span style="display:flex;"><span>Execution Time: 29.613 ms</span></span></code></pre></div>
</div>
<p>Mira el nodo <code>Bitmap Heap Scan on pedidos</code>: <code>actual time=0.026..0.496</code>,
parece que medio milisegundo. Pero tiene <code>loops=54</code>: se ejecutó 54 veces, una
por cada cliente del municipio. 0,496 ms × 54 ≈ <strong>27 ms</strong>, casi todo el tiempo
de la consulta (29,6 ms). Si no multiplicas, te vas a poner a optimizar el nodo
equivocado.</p>
<p>Un detalle más: cuando <code>loops</code> es mayor que 1, <code>rows</code> es la <strong>media por vuelta</strong>
(100 filas × 54 vueltas ≈ las 5 425 del nodo de arriba).</p>
<p>Para ver que los costes no son magia, tomemos el <code>Seq Scan</code> de más abajo
(<code>cost=0.00..19853.00</code>). La tabla <code>pedidos</code> ocupa 7 353 páginas y tiene
1 000 000 de filas. Con los parámetros por defecto, leer una página
secuencialmente cuesta 1, procesar una fila 0,01 y evaluar una condición 0,0025:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>7353 × 1  +  1 000 000 × 0,01  +  1 000 000 × 0,0025  =  19 853</span></span></code></pre></div>
</div>
<p>Cuadra exactamente. Un plan es aritmética, no un oráculo.</p>
<h2 id="regla-3-cómo-accede-a-los-datos">Regla 3: cómo accede a los datos <a class="ancla" href="#regla-3-c%c3%b3mo-accede-a-los-datos" aria-label="Enlace a esta sección">#</a></h2>
<p>Probemos con la consulta <code>SELECT * FROM pedidos WHERE cliente_id = 4242</code>, en
varias situaciones.</p>
<p><strong>Seq Scan.</strong> Sin índice sobre <code>cliente_id</code>, no hay otra opción que leer la
tabla entera:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Seq Scan on pedidos  (cost=0.00..19853.00 rows=100 width=27) (actual time=5.110..63.057 rows=103 loops=1)
</span></span><span style="display:flex;"><span>  Filter: (cliente_id = 4242)
</span></span><span style="display:flex;"><span>  Rows Removed by Filter: 999897
</span></span><span style="display:flex;"><span>  Buffers: shared read=7353
</span></span><span style="display:flex;"><span>Execution Time: 63.135 ms</span></span></code></pre></div>
</div>
<p>La línea clave es <code>Rows Removed by Filter: 999897</code>: leyó un millón de filas
para quedarse con 103.</p>
<p><strong>Bitmap Heap Scan.</strong> Con un índice sobre <code>cliente_id</code>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Bitmap Heap Scan on pedidos  (cost=5.20..371.46 rows=100 width=27) (actual time=0.071..0.700 rows=103 loops=1)
</span></span><span style="display:flex;"><span>  Recheck Cond: (cliente_id = 4242)
</span></span><span style="display:flex;"><span>  Heap Blocks: exact=102
</span></span><span style="display:flex;"><span>  -&gt;  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.17 rows=100 width=0) (actual time=0.048..0.048 rows=103 loops=1)
</span></span><span style="display:flex;"><span>        Index Cond: (cliente_id = 4242)
</span></span><span style="display:flex;"><span>Execution Time: 0.728 ms</span></span></code></pre></div>
</div>
<p>De 63 ms a 0,7 ms. Primero se recorre el índice y se construye un «mapa» de qué
páginas de la tabla contienen filas buscadas (<code>Bitmap Index Scan</code>); luego se
leen esas 102 páginas una sola vez y en orden (<code>Bitmap Heap Scan</code>). Es la
elección típica cuando salen unas decenas o cientos de filas dispersas por la
tabla.</p>
<p><strong>Index Scan.</strong> Para una sola fila por clave primaria, PostgreSQL va y vuelve
por el índice sin mapa intermedio:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Index Scan using pedidos_pkey on pedidos  (cost=0.42..8.44 rows=1 width=27) (actual time=0.042..0.042 rows=1 loops=1)
</span></span><span style="display:flex;"><span>  Index Cond: (id = 777777)
</span></span><span style="display:flex;"><span>Execution Time: 0.052 ms</span></span></code></pre></div>
</div>
<p><strong>Index Only Scan.</strong> Si sólo pides columnas que están en el propio índice, ni
siquiera toca la tabla:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Index Only Scan using idx_pedidos_cliente on pedidos  (cost=0.42..6.17 rows=100 width=4) (actual time=0.011..0.018 rows=103 loops=1)
</span></span><span style="display:flex;"><span>  Index Cond: (cliente_id = 4242)
</span></span><span style="display:flex;"><span>  Heap Fetches: 0
</span></span><span style="display:flex;"><span>Execution Time: 0.031 ms</span></span></code></pre></div>
</div>
<p>Ojo con <code>Heap Fetches: 0</code>. Un Index Only Scan necesita que el <em>mapa de
visibilidad</em> de la tabla esté al día, algo que mantiene <code>VACUUM</code>. Si
<code>Heap Fetches</code> es alto, el «only» es mentira: está yendo a la tabla igualmente.
En el laboratorio hago un <code>VACUUM pedidos;</code> justo antes para que salga limpio.</p>
<p><strong>El mito del Seq Scan malo.</strong> Cuando la condición se lleva casi media tabla:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Seq Scan on pedidos  (cost=0.00..22353.00 rows=598275 width=27) (actual time=0.011..83.618 rows=599873 loops=1)
</span></span><span style="display:flex;"><span>  Filter: ((cliente_id &gt;= 1) AND (cliente_id &lt;= 6000))
</span></span><span style="display:flex;"><span>Execution Time: 108.245 ms</span></span></code></pre></div>
</div>
<p>Aquí PostgreSQL <strong>tiene el índice a mano y decide no usarlo</strong>, y hace bien:
para devolver el 60 % de la tabla, leerla de principio a fin es más barato que
saltar del índice a la tabla seiscientas mil veces. Un Seq Scan no es un fallo:
es la herramienta correcta cuando se devuelve mucha parte de la tabla (o la
tabla es diminuta).</p>
<p>(Con un 30 % de la tabla, por cierto, PostgreSQL seguía eligiendo
<code>Bitmap Heap Scan</code>. El punto de cruce depende de los datos; lo que importa es
que lo calcula él y que puedes comprobarlo en el plan.)</p>
<h2 id="regla-3-segunda-parte-cómo-une-tablas">Regla 3, segunda parte: cómo une tablas <a class="ancla" href="#regla-3-segunda-parte-c%c3%b3mo-une-tablas" aria-label="Enlace a esta sección">#</a></h2>
<p>Los tres algoritmos de unión que vas a ver siempre son estos, y PostgreSQL elige
según cuántas filas cree que entran.</p>
<p><strong>Nested Loop</strong> (bucle anidado): para cada fila de la tabla externa busca en la
interna. Ideal con pocas filas externas y un índice en la interna. Es lo que
vimos en la regla 2.</p>
<p><strong>Hash Join</strong>: construye una tabla hash con la tabla más pequeña y recorre la
grande una sola vez consultándola. Es el rey cuando se unen muchas filas. Aquí,
todos los clientes contra todos los pedidos:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>HashAggregate  (cost=27838.11..27838.21 rows=8 width=52) (actual time=533.080..533.087 rows=8 loops=1)
</span></span><span style="display:flex;"><span>  -&gt;  Hash Join  (cost=359.00..20338.11 rows=1000000 width=18) (actual time=2.681..341.616 rows=1000000 loops=1)
</span></span><span style="display:flex;"><span>        Hash Cond: (p.cliente_id = c.id)
</span></span><span style="display:flex;"><span>        -&gt;  Seq Scan on pedidos p  (cost=0.00..17353.00 rows=1000000 width=10) (actual time=0.006..128.027 rows=1000000 loops=1)
</span></span><span style="display:flex;"><span>        -&gt;  Hash  (cost=234.00..234.00 rows=10000 width=16) (actual time=2.593..2.595 rows=10000 loops=1)
</span></span><span style="display:flex;"><span>              Buckets: 16384  Batches: 1  Memory Usage: 597kB
</span></span><span style="display:flex;"><span>              -&gt;  Seq Scan on clientes c  (cost=0.00..234.00 rows=10000 width=16) (actual time=0.003..0.890 rows=10000 loops=1)
</span></span><span style="display:flex;"><span>Execution Time: 533.194 ms</span></span></code></pre></div>
</div>
<p>Se construye el hash con los 10 000 clientes (597 kB) y se recorren los
pedidos una vez. Fíjate en <code>Batches: 1</code>: significa que el hash cabió en memoria
(<code>work_mem</code>). Si ves <code>Batches</code> mayor que 1, el hash se ha desbordado a disco y
la unión se vuelve bastante más lenta.</p>
<p><strong>Merge Join</strong>: une dos entradas ya ordenadas por la clave de unión, avanzando
en paralelo por ambas. Es una buena opción cuando las dos entradas vienen
ordenadas «gratis», por ejemplo desde índices.</p>
<p>Una forma muy instructiva de aprender es <em>forzar</em> a PostgreSQL a elegir otro
algoritmo y comparar. En el laboratorio lo hago con
<code>SET enable_hashjoin = off;</code> y compañía (sólo para experimentar, nunca como
solución en producción). La misma consulta, tres algoritmos:</p>
<table>
  <thead>
      <tr>
          <th>Algoritmo</th>
          <th>Coste estimado</th>
          <th>Tiempo real</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Hash Join (elección de PostgreSQL)</td>
          <td>27 838</td>
          <td>533 ms</td>
      </tr>
      <tr>
          <td>Nested Loop (con <code>Memoize</code>)</td>
          <td>52 868</td>
          <td>664 ms</td>
      </tr>
      <tr>
          <td>Merge Join</td>
          <td>68 320</td>
          <td>887 ms</td>
      </tr>
  </tbody>
</table>
<p>El orden de los costes estimados coincide con el de los tiempos reales. Cuando
eso pasa, el planificador está bien informado. Cuando no, mira la regla 4.</p>
<p>El Nested Loop merece una mención: PostgreSQL 14 y posteriores colocan un nodo
<code>Memoize</code> delante del índice interno, que recuerda resultados ya buscados:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>-&gt;  Memoize  (cost=0.30..0.31 rows=1 width=16) (actual time=0.000..0.000 rows=1 loops=1000000)
</span></span><span style="display:flex;"><span>      Cache Key: p.cliente_id
</span></span><span style="display:flex;"><span>      Hits: 990000  Misses: 10000  Evictions: 0  Overflows: 0  Memory Usage: 1133kB</span></span></code></pre></div>
</div>
<p>Un millón de vueltas, 990 000 aciertos de caché y sólo 10 000 búsquedas reales
en el índice. Por eso un Nested Loop sobre un millón de filas no salió
catastrófico. Mira el <code>loops=1000000</code> y recuerda la regla 2.</p>
<p>El Merge Join, por su parte, necesita las dos entradas ordenadas. Aquí las
obtiene de dos <code>Index Scan</code>, y el de <code>pedidos</code> salta de una página a otra de la
tabla siguiendo el índice, lo que se nota en los casi un millón de accesos a
buffers (<code>shared hit=990160</code>).</p>
<h2 id="regla-4-compara-siempre-estimado-y-real">Regla 4: compara siempre estimado y real <a class="ancla" href="#regla-4-compara-siempre-estimado-y-real" aria-label="Enlace a esta sección">#</a></h2>
<p>Esta es la regla que más tiempo me ha ahorrado. En cada nodo tienes el <code>rows=</code>
que PostgreSQL <em>esperaba</em> y el <code>rows=</code> que <em>salió</em>. Si difieren en uno o dos
órdenes de magnitud, el problema no es el índice ni el algoritmo: es que el
planificador decide a ciegas con información equivocada.</p>
<p>Un ejemplo con tres filtros sobre <code>clientes</code> (provincia, municipio y código
postal):</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Seq Scan on clientes  (cost=0.00..309.00 rows=1 width=74) (actual time=0.015..0.749 rows=23 loops=1)
</span></span><span style="display:flex;"><span>  Filter: ((provincia = &#39;Provincia 1&#39;::text) AND (municipio = &#39;Municipio 7&#39;::text) AND (codigo_postal = &#39;00070&#39;::text))
</span></span><span style="display:flex;"><span>  Rows Removed by Filter: 9977</span></span></code></pre></div>
</div>
<p>Estimó 1 fila, salieron 23. Por qué: PostgreSQL asume que las columnas son
<strong>independientes</strong> y multiplica sus selectividades. Pero aquí cada código
postal pertenece a un único municipio y cada municipio a una única provincia,
así que los tres filtros dicen lo mismo y la selectividad real es mucho mayor
que el producto.</p>
<p>Dentro de una unión con <code>pedidos</code> y <code>lineas_pedido</code>, el error se arrastra y se
amplifica:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Aggregate  ...
</span></span><span style="display:flex;"><span>  -&gt;  Nested Loop  (cost=5.64..746.27 rows=286 width=10) (actual time=0.137..55.855 rows=6735 loops=1)
</span></span><span style="display:flex;"><span>        -&gt;  Nested Loop  (cost=5.21..684.97 rows=100 width=4) (actual time=0.048..5.643 rows=2245 loops=1)
</span></span><span style="display:flex;"><span>              -&gt;  Seq Scan on clientes c  (cost=0.00..309.00 rows=1 width=4) (actual time=0.014..1.071 rows=23 loops=1)</span></span></code></pre></div>
</div>
<p>Estimado 286 filas en la unión, reales 6 735: <strong>23 veces menos</strong>. En este caso
el plan sigue siendo razonable, pero con una estimación así de mala el
planificador puede elegir un Nested Loop donde un Hash Join sería mucho mejor.
Aquí hemos tenido suerte.</p>
<p>El arreglo no es un índice, sino darle al planificador información sobre la
correlación con <strong>estadísticas extendidas</strong>:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#66d9ef">CREATE</span> <span style="color:#66d9ef">STATISTICS</span> clientes_geo (dependencies, ndistinct)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">ON</span> provincia, municipio, codigo_postal <span style="color:#66d9ef">FROM</span> clientes;
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">ANALYZE</span> clientes;</span></span></code></pre></div>
</div>
<p><code>dependencies</code> es la que corrige los filtros de igualdad como este;
<code>ndistinct</code> ayuda con los <code>GROUP BY</code> sobre varias columnas. El resultado:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Seq Scan on clientes  (cost=0.00..309.00 rows=23 width=74) (actual time=0.024..1.043 rows=23 loops=1)
</span></span><span style="display:flex;"><span>...
</span></span><span style="display:flex;"><span>Nested Loop  (cost=5.64..9322.65 rows=6573 width=10) (actual time=0.060..14.631 rows=6735 loops=1)</span></span></code></pre></div>
</div>
<p>Estimado 23, real 23. En la unión, 6 573 estimadas frente a 6 735 reales.</p>
<p>Una advertencia de honestidad: en este laboratorio la <strong>forma</strong> del plan no
cambió, así que la consulta no mejora «gracias» a la estadística. Si compruebas
los números verás que pasa de 58 ms a 17 ms, pero eso es sobre todo caché: en
la primera salida el último nodo lee de fuera de <code>shared_buffers</code>
(<code>read=4047</code>) y en la segunda no. Estimar bien no garantiza un plan distinto;
lo que garantiza es que, cuando el plan <em>tenga</em> que cambiar, tome la decisión
con datos correctos.</p>
<h2 id="buffers-lenta-por-leer-o-lenta-por-trabajar">BUFFERS: ¿lenta por leer o lenta por trabajar? <a class="ancla" href="#buffers-lenta-por-leer-o-lenta-por-trabajar" aria-label="Enlace a esta sección">#</a></h2>
<p><code>BUFFERS</code> cuenta las páginas (de 8 kB) que toca cada nodo:</p>
<ul>
<li><strong><code>shared hit</code></strong>: la página ya estaba en la caché de PostgreSQL
(<code>shared_buffers</code>).</li>
<li><strong><code>shared read</code></strong>: no estaba y hubo que pedirla fuera. Ojo, «fuera» puede ser
la caché del sistema operativo y no necesariamente el disco.</li>
</ul>
<p>El mismo <code>Seq Scan</code> sobre <code>pedidos</code>, recién arrancado el servidor y luego con
la tabla ya caliente:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>-- Frío (recién reiniciado)
</span></span><span style="display:flex;"><span>Seq Scan on pedidos ...
</span></span><span style="display:flex;"><span>  Buffers: shared read=7353
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>-- Caliente
</span></span><span style="display:flex;"><span>Seq Scan on pedidos ...
</span></span><span style="display:flex;"><span>  Buffers: shared hit=7353</span></span></code></pre></div>
</div>
<p>Siempre las mismas 7 353 páginas, que son las que ocupa la tabla. Lo que cambia
es de dónde salen. Esto te ayuda a distinguir dos tipos de lentitud: la que
viene de <strong>leer</strong> mucho (muchos <code>read</code>) y la que viene de <strong>trabajar</strong> mucho
(muchos <code>hit</code> y mucho tiempo de CPU). Y te avisa de un clásico: la consulta que
«va rápido la segunda vez» no está arreglada, está en caché.</p>
<h2 id="el-n1-visto-en-un-plan">El N+1, visto en un plan <a class="ancla" href="#el-n1-visto-en-un-plan" aria-label="Enlace a esta sección">#</a></h2>
<p>Si vienes de ORMs, el N+1 es el patrón de ejecutar una consulta por cada fila
de otra. Dentro de PostgreSQL tiene su versión: la subconsulta correlacionada.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#66d9ef">SELECT</span> p.id,
</span></span><span style="display:flex;"><span>       (<span style="color:#66d9ef">SELECT</span> <span style="color:#66d9ef">sum</span>(l.cantidad <span style="color:#f92672">*</span> l.precio)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">FROM</span> lineas_pedido l
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">WHERE</span> l.pedido_id <span style="color:#f92672">=</span> p.id) <span style="color:#66d9ef">AS</span> importe
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">FROM</span> pedidos p
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">WHERE</span> p.cliente_id <span style="color:#66d9ef">BETWEEN</span> <span style="color:#ae81ff">4242</span> <span style="color:#66d9ef">AND</span> <span style="color:#ae81ff">4261</span>;</span></span></code></pre></div>
</div>
<p>El plan:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Bitmap Heap Scan on pedidos p  (cost=28.27..20915.11 rows=1936 width=36) (actual time=0.629..43.262 rows=2000 loops=1)
</span></span><span style="display:flex;"><span>  SubPlan 1
</span></span><span style="display:flex;"><span>    -&gt;  Aggregate  (cost=8.51..8.52 rows=1 width=32) (actual time=0.018..0.018 rows=1 loops=2000)
</span></span><span style="display:flex;"><span>          -&gt;  Index Scan using idx_lineas_pedido on lineas_pedido l  (cost=0.43..8.48 rows=3 width=10) (actual time=0.016..0.017 rows=3 loops=2000)
</span></span><span style="display:flex;"><span>Execution Time: 43.501 ms</span></span></code></pre></div>
</div>
<p><code>loops=2000</code>: el <code>SubPlan</code> se ejecuta una vez por pedido. Cada vuelta cuesta
0,018 ms, que parece nada, pero 0,018 × 2000 = <strong>36 ms</strong> de los 43,5 totales.
Es la regla 2 en acción. La versión con <code>JOIN</code> y <code>GROUP BY</code> hace el mismo
trabajo en 11,6 ms.</p>
<p>Dentro de la base de datos la diferencia es moderada porque no hay red entre
medias. El N+1 «de verdad» es el que hace la aplicación: una consulta por
pedido, cada una con su viaje de ida y vuelta al servidor. El laboratorio lo
mide con <code>n_mas_1.sh</code>, que lanza 2 000 consultas sueltas y luego una sola con
<code>JOIN</code>, ambas desde una única sesión de <code>psql</code> y por socket Unix local (la red
más rápida que existe):</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-console" data-lang="console"><span style="display:flex;"><span>ignacio@zeus:~/blog-public-code/lab-explain$ ./n_mas_1.sh
</span></span><span style="display:flex;"><span>Pedidos a calcular: 2000
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span>== N+1: 2000 consultas sueltas
</span></span><span style="display:flex;"><span>real	0m0.226s
</span></span><span style="display:flex;"><span><span style="color:#960050;background-color:#1e0010">
</span></span></span><span style="display:flex;"><span>== Una sola consulta con JOIN
</span></span><span style="display:flex;"><span>real	0m0.056s
</span></span></code></pre></div>
</div>
<p>En cinco ejecuciones, el N+1 tardó entre 226 y 256 ms y el <code>JOIN</code> entre 51 y
93 ms: entre 2,5 y 4,5 veces más lento, <strong>sin red de por medio</strong>. Con un servidor remoto,
cada viaje cuesta además la latencia de red, y la diferencia crece a base de
bien.</p>
<p>Si leíste la serie de GraphQL, ya me has visto dar la lata con el N+1 y con
<code>DataLoader</code>. Aquí lo único que cambia es dónde mirar: en el plan, un <code>loops</code>
enorme.</p>
<h2 id="tres-autopsias-el-índice-existe-y-postgresql-pasa-de-él">Tres autopsias: el índice existe y PostgreSQL pasa de él <a class="ancla" href="#tres-autopsias-el-%c3%adndice-existe-y-postgresql-pasa-de-%c3%a9l" aria-label="Enlace a esta sección">#</a></h2>
<p>Volvamos a la pregunta del principio.</p>
<h3 id="1-función-aplicada-a-la-columna-indexada">1. Función aplicada a la columna indexada <a class="ancla" href="#1-funci%c3%b3n-aplicada-a-la-columna-indexada" aria-label="Enlace a esta sección">#</a></h3>
<p>Hay un índice sobre <code>pedidos.fecha</code>. Esta consulta busca los pedidos de un día:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#66d9ef">SELECT</span> <span style="color:#f92672">*</span> <span style="color:#66d9ef">FROM</span> pedidos <span style="color:#66d9ef">WHERE</span> to_char(fecha, <span style="color:#e6db74">&#39;YYYY-MM-DD&#39;</span>) <span style="color:#f92672">=</span> <span style="color:#e6db74">&#39;2024-03-15&#39;</span>;</span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Seq Scan on pedidos  (cost=0.00..24853.00 rows=5000 width=27) (actual time=0.104..459.164 rows=726 loops=1)
</span></span><span style="display:flex;"><span>  Filter: (to_char((fecha)::timestamp with time zone, &#39;YYYY-MM-DD&#39;::text) = &#39;2024-03-15&#39;::text)
</span></span><span style="display:flex;"><span>  Rows Removed by Filter: 999274
</span></span><span style="display:flex;"><span>Execution Time: 459.294 ms</span></span></code></pre></div>
</div>
<p>El índice está ordenado por <code>fecha</code>, no por <code>to_char(fecha, ...)</code>. Para
PostgreSQL esa función es una caja negra: no puede deducir en qué parte del
índice caería el resultado, así que no tiene más remedio que calcularla fila a
fila sobre el millón de filas.</p>
<p>Fíjate también en <code>rows=5000</code> frente a 726 reales: ante una expresión opaca
PostgreSQL no tiene estadísticas y usa una estimación por defecto (un 0,5 % de
la tabla).</p>
<p>La solución es escribir la condición sobre la columna «desnuda»:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#66d9ef">SELECT</span> <span style="color:#f92672">*</span> <span style="color:#66d9ef">FROM</span> pedidos <span style="color:#66d9ef">WHERE</span> fecha <span style="color:#f92672">=</span> DATE <span style="color:#e6db74">&#39;2024-03-15&#39;</span>;</span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Bitmap Heap Scan on pedidos  (cost=9.94..2118.47 rows=712 width=27) (actual time=0.235..1.202 rows=726 loops=1)
</span></span><span style="display:flex;"><span>  Recheck Cond: (fecha = &#39;2024-03-15&#39;::date)
</span></span><span style="display:flex;"><span>  -&gt;  Bitmap Index Scan on idx_pedidos_fecha  (cost=0.00..9.77 rows=712 width=0) (actual time=0.141..0.141 rows=726 loops=1)
</span></span><span style="display:flex;"><span>Execution Time: 1.272 ms</span></span></code></pre></div>
</div>
<p>459 ms → 1,3 ms, y además la estimación (712) ya se parece a la realidad (726).
Es la misma regla para <code>date_trunc</code>, <code>lower()</code>, <code>extract()</code> o un cast sobre la
columna: si la envuelves en una función, el índice normal no la entiende. O
reescribes la condición, o creas un índice sobre la expresión.</p>
<h3 id="2-tipos-que-no-encajan">2. Tipos que no encajan <a class="ancla" href="#2-tipos-que-no-encajan" aria-label="Enlace a esta sección">#</a></h3>
<p><code>pedidos.cliente_id</code> es un <code>integer</code> con índice. ¿Y si lo comparamos con un
número con decimales, como hacen algunos drivers o ORMs al enviar parámetros?</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#66d9ef">SELECT</span> <span style="color:#f92672">*</span> <span style="color:#66d9ef">FROM</span> pedidos <span style="color:#66d9ef">WHERE</span> cliente_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">4242</span>.<span style="color:#ae81ff">0</span>;</span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Seq Scan on pedidos  (cost=0.00..22353.00 rows=5000 width=27) (actual time=12.194..114.285 rows=103 loops=1)
</span></span><span style="display:flex;"><span>  Filter: ((cliente_id)::numeric = 4242.0)
</span></span><span style="display:flex;"><span>  Rows Removed by Filter: 999897
</span></span><span style="display:flex;"><span>Execution Time: 114.316 ms</span></span></code></pre></div>
</div>
<p>La pista está en el <code>Filter</code>: <code>(cliente_id)::numeric</code>. Como <code>4242.0</code> es un
<code>numeric</code>, PostgreSQL convierte la <strong>columna</strong> a <code>numeric</code> para poder comparar,
y un índice sobre <code>integer</code> no sirve para una comparación sobre <code>numeric</code>.
Misma consulta con el literal correcto:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-text" data-lang="text"><span style="display:flex;"><span>Bitmap Heap Scan on pedidos  (cost=5.20..371.46 rows=100 width=27) (actual time=0.032..0.138 rows=103 loops=1)
</span></span><span style="display:flex;"><span>  -&gt;  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.17 rows=100 width=0) (actual time=0.015..0.015 rows=103 loops=1)
</span></span><span style="display:flex;"><span>Execution Time: 0.161 ms</span></span></code></pre></div>
</div>
<p>114 ms → 0,16 ms. Cuando un índice «no se usa» y no sabes por qué, lee el
<code>Filter</code> con atención: un <code>::tipo</code> pegado a tu columna delata este problema.</p>
<h3 id="3-poca-selectividad">3. Poca selectividad <a class="ancla" href="#3-poca-selectividad" aria-label="Enlace a esta sección">#</a></h3>
<p>Con un índice sobre <code>estado</code>, la misma columna con tres valores distintos
produce tres comportamientos distintos:</p>
<table>
  <thead>
      <tr>
          <th>Condición</th>
          <th>Filas</th>
          <th>Plan elegido</th>
          <th>Tiempo</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><code>estado = 'entregado'</code></td>
          <td>899 663 (90 %)</td>
          <td>Seq Scan</td>
          <td>128 ms</td>
      </tr>
      <tr>
          <td><code>estado = 'pendiente'</code></td>
          <td>25 177 (2,5 %)</td>
          <td>Bitmap Heap Scan</td>
          <td>17 ms</td>
      </tr>
      <tr>
          <td><code>estado = 'devuelto'</code></td>
          <td>4 895 (0,5 %)</td>
          <td>Index Scan</td>
          <td>2,9 ms</td>
      </tr>
  </tbody>
</table>
<p>No hay nada roto. El mismo índice sirve muy bien para el 0,5 % y es inútil
para el 90 %, y PostgreSQL decide en cada consulta comparando costes con las
estadísticas de la columna. Si alguna vez te preguntas por qué el índice de
una columna con pocos valores distintos «no funciona», probablemente sí
funciona, pero para los valores raros.</p>
<h2 id="herramientas-para-no-leer-planes-a-mano">Herramientas para no leer planes a mano <a class="ancla" href="#herramientas-para-no-leer-planes-a-mano" aria-label="Enlace a esta sección">#</a></h2>
<p>Cuando el plan es largo, lo cómodo es visualizarlo:</p>
<ul>
<li><a href="https://explain.depesz.com/" target="_blank" rel="noopener">explain.depesz.com</a>: pegas el plan y marca en
colores los nodos que más tiempo consumen.</li>
<li><a href="https://explain.dalibo.com/" target="_blank" rel="noopener">explain.dalibo.com</a>: visualización en forma de
árbol y diagrama. Está construido sobre
<a href="https://github.com/dalibo/pev2" target="_blank" rel="noopener">PEV2</a>, que es software libre.</li>
</ul>
<p>Un consejo de higiene antes de pegar nada en un servicio público: el plan
contiene nombres de tablas, de columnas e incluso valores literales de tus
consultas. Si trabajas con datos internos, anonimiza el plan o usa una
herramienta que puedas alojar tú.</p>
<h2 id="qué-cambia-en-postgresql-18">Qué cambia en PostgreSQL 18 <a class="ancla" href="#qu%c3%a9-cambia-en-postgresql-18" aria-label="Enlace a esta sección">#</a></h2>
<p>Todas las salidas de esta entrada son de PostgreSQL 16.15. Las versiones
recientes mejoran <code>EXPLAIN</code>: en PostgreSQL 18, <code>EXPLAIN ANALYZE</code> incluye
<code>BUFFERS</code> por defecto, y los nodos de índice muestran una línea
<code>Index Searches</code> con el número de recorridos que hizo el índice (más detalle en
<a href="https://www.pgmustard.com/blog/what-do-index-searches-in-explain-mean" target="_blank" rel="noopener">el artículo de pgMustard</a>).
La forma de leer el plan es la misma; sólo verás alguna línea más.</p>
<h2 id="checklist-de-cinco-preguntas">Checklist de cinco preguntas <a class="ancla" href="#checklist-de-cinco-preguntas" aria-label="Enlace a esta sección">#</a></h2>
<p>Ante cualquier plan, en este orden:</p>
<ol>
<li><strong>¿Dónde está el tiempo?</strong> Busca el nodo con mayor <code>actual time</code>
<strong>multiplicado por <code>loops</code></strong>. Ahí es donde optimizar.</li>
<li><strong>¿Coinciden <code>rows</code> estimado y real?</strong> Si difieren por órdenes de magnitud,
revisa estadísticas (<code>ANALYZE</code>, <code>CREATE STATISTICS</code>) antes de tocar índices.</li>
<li><strong>¿Cómo accede a la tabla?</strong> Un <code>Seq Scan</code> con un <code>Rows Removed by Filter</code>
enorme y pocas filas devueltas pide un índice. Con muchas filas devueltas,
está bien.</li>
<li><strong>¿Hay algo raro pegado a mi columna en el <code>Filter</code>/<code>Index Cond</code>?</strong> Una
función, un <code>::cast</code>&hellip; eso explica un índice ignorado.</li>
<li><strong>¿Es lectura o trabajo?</strong> Mira <code>BUFFERS</code>: muchos <code>read</code> indican que hay
que traer datos de fuera; muchos <code>hit</code> con mucho tiempo, que la CPU está
trabajando de más.</li>
</ol>
<h2 id="para-quedarte-con-algo">Para quedarte con algo <a class="ancla" href="#para-quedarte-con-algo" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li><code>EXPLAIN</code> estima, <code>EXPLAIN ANALYZE</code> ejecuta. Usa <code>BEGIN</code>/<code>ROLLBACK</code> con DML.</li>
<li>El plan se lee de dentro hacia fuera y el tiempo real es <strong>por vuelta</strong>.</li>
<li>Compara siempre estimado con real: ahí se esconde la mitad de los problemas.</li>
<li>Un <code>Seq Scan</code> no es malo por sí mismo.</li>
<li>Si un índice no se usa, mira el <code>Filter</code>: tipos, funciones y selectividad.</li>
</ul>
<p>Todo el código está en
<a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-explain" target="_blank" rel="noopener"><code>lab-explain/</code></a>
con las salidas de referencia en <code>salidas/</code>. Si lo ejecutas y te salen planes
distintos, fíjate en la forma, no en los milisegundos, y cuéntamelo: es la mejor
manera de aprender cuál fue la decisión del planificador.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_89956f4fb17100b7.png"/></item><item><title>Cuando el consumidor se cae: ack, reencolado y dead letter</title><link>https://www.igalvan.es/posts/2026/colas-cuando-el-consumidor-se-cae/</link><pubDate>Tue, 03 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/colas-cuando-el-consumidor-se-cae/</guid><description><![CDATA[<p>En la <a href="/posts/2026/colas-de-mensajes-para-gente-de-sincrono/">entrada anterior</a> saqué el envío del correo del endpoint y lo mandé a una cola de RabbitMQ. El endpoint pasó de dos segundos a cuarenta milisegundos y un <code>worker.py</code> se encarga de los correos. Todo bonito mientras nada falla.</p>
<p>Esta entrada va de que algo falle. Cuatro veces, cada una peor que la anterior, y arreglándolas por orden.</p>
<h2 id="fallo-1-el-worker-muere-y-el-mensaje-desaparece">Fallo 1: el worker muere y el mensaje desaparece <a class="ancla" href="#fallo-1-el-worker-muere-y-el-mensaje-desaparece" aria-label="Enlace a esta sección">#</a></h2>
<p>El worker de la entrada anterior tenía esto:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)</span></span></code></pre></div>
</div>
<p><code>auto_ack=True</code> significa que RabbitMQ da el mensaje por entregado en el momento en que lo manda al consumidor. Vamos a ver qué implica.</p>
<p>Arranca el worker, lanza un pedido, y en los dos segundos de <code>sleep</code> que simulan el envío del correo, mata el proceso sin contemplaciones:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 510
Killed</code></pre>
</div>
<p>(Desde otra terminal: <code>pkill -9 -f worker.py</code>. Tiene que ser <code>-9</code>; con un <code>Ctrl+C</code> pika cierra la conexión limpiamente y no es lo que quiero probar.)</p>
<p>Ahora mira la interfaz web, pestaña <em>Queues</em>, cola <code>correos</code>: <em>Ready</em> 0, <em>Unacked</em> 0, <em>Total</em> 0. Arranca el worker otra vez: no recibe nada. El pedido 510 está en la base de datos y su correo de confirmación no existe ni va a existir. Nadie se ha enterado.</p>
<p>Esto es lo que compra <code>auto_ack=True</code>: rendimiento a cambio de que cualquier caída del consumidor se lleve lo que tenía entre manos. Hay casos en que vale (métricas, logs, cosas que si se pierde una no pasa nada), pero un correo de confirmación no es uno de ellos.</p>
<h2 id="arreglo-1-ack-manual">Arreglo 1: ack manual <a class="ancla" href="#arreglo-1-ack-manual" aria-label="Enlace a esta sección">#</a></h2>
<p>El consumidor tiene que decirle a RabbitMQ &ldquo;ya he terminado con este&rdquo; <strong>después</strong> de haber terminado, no antes.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] recibido pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">...</span>
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_qos(prefetch_count<span style="color:#f92672">=</span><span style="color:#ae81ff">1</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">False</span>)</span></span></code></pre></div>
</div>
<p>Dos cambios. <code>auto_ack=False</code> y el <code>basic_ack</code> explícito al final de <code>procesar</code>, con el <code>delivery_tag</code> que identifica esa entrega concreta. Y <code>basic_qos(prefetch_count=1)</code>: sin esto, RabbitMQ le manda al consumidor todos los mensajes que haya en la cola de golpe y los deja todos en <em>Unacked</em> mientras el worker los va procesando uno a uno; con <code>prefetch_count=1</code> le manda uno, espera el ack, y manda el siguiente. Para un worker que tarda dos segundos por mensaje es lo que quieres.</p>
<p>Repite el experimento. Lanza el pedido, y durante el <code>sleep</code> mira la interfaz: <em>Ready</em> 0, <strong>Unacked 1</strong>. El mensaje está entregado pero no confirmado. Ahora <code>pkill -9</code>:</p>
<p><em>Ready 1</em>, <em>Unacked 0</em>. RabbitMQ ha detectado que la conexión del consumidor se ha cerrado sin confirmar y ha devuelto el mensaje a la cola. Arranca el worker:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 511
[correo] confirmación del pedido 511 enviada</code></pre>
</div>
<p>El correo se envía. Con un detalle que importa y que dejo apuntado para la tercera entrada: en <code>metodo.redelivered</code> viene <code>True</code>. RabbitMQ sabe que este mensaje ya se entregó una vez, y te lo dice.</p>
<h2 id="fallo-2-el-correo-falla-y-el-worker-se-cae">Fallo 2: el correo falla y el worker se cae <a class="ancla" href="#fallo-2-el-correo-falla-y-el-worker-se-cae" aria-label="Enlace a esta sección">#</a></h2>
<p>Hasta ahora el worker moría por causas externas. Vamos a que falle por las suyas. Hago que el servidor de correo simulado rechace los pedidos grandes:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> float(pedido[<span style="color:#e6db74">&#34;total&#34;</span>]) <span style="color:#f92672">&gt;</span> <span style="color:#ae81ff">1000</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">raise</span> <span style="color:#a6e22e">RuntimeError</span>(<span style="color:#e6db74">&#34;el servidor de correo ha rechazado el mensaje&#34;</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)</span></span></code></pre></div>
</div>
<p>Lanza un pedido de 2000 euros:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 512
Traceback (most recent call last):
  ...
RuntimeError: el servidor de correo ha rechazado el mensaje</code></pre>
</div>
<p>El worker se ha caído entero. Como no había hecho ack, el mensaje vuelve a <em>Ready</em>. Arranca el worker: recibe el 512, falla, se cae. Y así hasta que alguien edite el código. Mientras tanto, todos los demás correos, los que sí se podrían enviar, están detrás del 512 esperando.</p>
<p>Un mensaje que tumba al consumidor cada vez que lo intenta tiene nombre: <em>poison message</em>. Y la solución ingenua lo empeora.</p>
<h2 id="arreglo-2-malo-capturar-la-excepción-y-reencolar">Arreglo 2 (malo): capturar la excepción y reencolar <a class="ancla" href="#arreglo-2-malo-capturar-la-excepci%c3%b3n-y-reencolar" aria-label="Enlace a esta sección">#</a></h2>
<p>Lo primero que se le ocurre a cualquiera:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] recibido pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">try</span>:
</span></span><span style="display:flex;"><span>        enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">except</span> <span style="color:#a6e22e">Exception</span> <span style="color:#66d9ef">as</span> e:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] error: </span><span style="color:#e6db74">{</span>e<span style="color:#e6db74">}</span><span style="color:#e6db74">, reencolando&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>        canal<span style="color:#f92672">.</span>basic_nack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag, requeue<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)</span></span></code></pre></div>
</div>
<p><code>basic_nack</code> con <code>requeue=True</code> es &ldquo;no he podido, devuélvelo a la cola&rdquo;. Y RabbitMQ lo devuelve, al principio de la cola, y se lo vuelve a entregar al mismo worker, que vuelve a fallar:</p>
<div class="codeblock"><pre tabindex="0"><code>[worker] recibido pedido 512
[worker] error: el servidor de correo ha rechazado el mensaje, reencolando
[worker] recibido pedido 512
[worker] error: el servidor de correo ha rechazado el mensaje, reencolando
[worker] recibido pedido 512
...</code></pre>
</div>
<p>El worker ya no se cae, pero está en un bucle infinito con el mismo mensaje, cada dos segundos, para siempre, y en la interfaz ves el contador de <em>Redelivered</em> subir sin parar. Los demás correos siguen sin salir. Hemos cambiado un proceso muerto por un proceso ocupado haciendo nada.</p>
<h2 id="arreglo-2-bueno-reintentos-con-espera-y-una-cola-de-fallidos">Arreglo 2 (bueno): reintentos con espera y una cola de fallidos <a class="ancla" href="#arreglo-2-bueno-reintentos-con-espera-y-una-cola-de-fallidos" aria-label="Enlace a esta sección">#</a></h2>
<p>Lo que quiero es: si el correo falla, esperar un poco y volver a intentarlo, porque igual el servidor de correo estaba saturado y a la tercera va. Y si tras unos cuantos intentos sigue fallando, apartar el mensaje a un sitio donde alguien pueda mirarlo, y seguir con los demás.</p>
<p>RabbitMQ tiene la pieza para esto: el <strong>dead letter exchange</strong> (DLX). Es un atributo de la cola que dice &ldquo;cuando un mensaje de esta cola sea rechazado o caduque, en vez de tirarlo, mándalo a este exchange con esta clave&rdquo;. Con eso y una cola intermedia con caducidad se monta el circuito entero sin escribir ningún temporizador:</p>
<div class="codeblock"><pre tabindex="0"><code>correos ──(nack)──▶ correos.reintentos ──(caduca a los 5 s)──▶ correos
   │
   └──(tras 3 intentos, el worker lo publica)──▶ correos.fallidos</code></pre>
</div>
<p>Las declaraciones:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># cola.py (modificado)</span>
</span></span><span style="display:flex;"><span>COLA <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos&#34;</span>
</span></span><span style="display:flex;"><span>COLA_REINTENTOS <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos.reintentos&#34;</span>
</span></span><span style="display:flex;"><span>COLA_FALLIDOS <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos.fallidos&#34;</span>
</span></span><span style="display:flex;"><span>MAX_INTENTOS <span style="color:#f92672">=</span> <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">declarar_colas</span>(canal) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(
</span></span><span style="display:flex;"><span>        queue<span style="color:#f92672">=</span>COLA,
</span></span><span style="display:flex;"><span>        durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>,
</span></span><span style="display:flex;"><span>        arguments<span style="color:#f92672">=</span>{
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-exchange&#34;</span>: <span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-routing-key&#34;</span>: COLA_REINTENTOS,
</span></span><span style="display:flex;"><span>        },
</span></span><span style="display:flex;"><span>    )
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(
</span></span><span style="display:flex;"><span>        queue<span style="color:#f92672">=</span>COLA_REINTENTOS,
</span></span><span style="display:flex;"><span>        durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>,
</span></span><span style="display:flex;"><span>        arguments<span style="color:#f92672">=</span>{
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-message-ttl&#34;</span>: <span style="color:#ae81ff">5000</span>,
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-exchange&#34;</span>: <span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;x-dead-letter-routing-key&#34;</span>: COLA,
</span></span><span style="display:flex;"><span>        },
</span></span><span style="display:flex;"><span>    )
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(queue<span style="color:#f92672">=</span>COLA_FALLIDOS, durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)</span></span></code></pre></div>
</div>
<p><code>correos</code> manda sus rechazados a <code>correos.reintentos</code>. Esa cola no tiene consumidores; los mensajes se quedan ahí cinco segundos (<code>x-message-ttl</code>), caducan, y al caducar su propio DLX los devuelve a <code>correos</code>. <code>correos.fallidos</code> es una cola normal donde van a parar los que se rinden.</p>
<p>Un aviso antes de ejecutar nada: <code>correos</code> ya existe de la entrada anterior, declarada sin argumentos, y RabbitMQ no deja cambiar los argumentos de una cola existente. El <code>queue_declare</code> nuevo falla con un <code>PRECONDITION_FAILED</code>. Hay que borrarla primero, desde la interfaz web o con:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ podman compose exec rabbitmq rabbitmqctl delete_queue correos</code></pre>
</div>
<p>(Y que <code>publicar()</code> en <code>cola.py</code> llame a <code>declarar_colas(canal)</code> en vez de a su <code>queue_declare</code> suelto, para que productor y consumidor declaren lo mismo.)</p>
<p>Ahora el worker. ¿Cómo sabe cuántas veces ha fallado ya un mensaje? RabbitMQ lo apunta por él: cada vez que un mensaje pasa por un DLX, le añade (o actualiza) una cabecera <code>x-death</code> con la cola de origen, el motivo y un contador.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py (versión final)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> time
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> pika
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> cola <span style="color:#f92672">import</span> COLA, COLA_FALLIDOS, MAX_INTENTOS, URL, declarar_colas
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> float(pedido[<span style="color:#e6db74">&#34;total&#34;</span>]) <span style="color:#f92672">&gt;</span> <span style="color:#ae81ff">1000</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">raise</span> <span style="color:#a6e22e">RuntimeError</span>(<span style="color:#e6db74">&#34;el servidor de correo ha rechazado el mensaje&#34;</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">intentos_previos</span>(propiedades) <span style="color:#f92672">-&gt;</span> int:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Cuántas veces ha sido rechazado este mensaje desde la cola principal.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    muertes <span style="color:#f92672">=</span> (propiedades<span style="color:#f92672">.</span>headers <span style="color:#f92672">or</span> {})<span style="color:#f92672">.</span>get(<span style="color:#e6db74">&#34;x-death&#34;</span>, [])
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> sum(m[<span style="color:#e6db74">&#34;count&#34;</span>] <span style="color:#66d9ef">for</span> m <span style="color:#f92672">in</span> muertes <span style="color:#66d9ef">if</span> m[<span style="color:#e6db74">&#34;queue&#34;</span>] <span style="color:#f92672">==</span> COLA <span style="color:#f92672">and</span> m[<span style="color:#e6db74">&#34;reason&#34;</span>] <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;rejected&#34;</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    intento <span style="color:#f92672">=</span> intentos_previos(propiedades) <span style="color:#f92672">+</span> <span style="color:#ae81ff">1</span>
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">, intento </span><span style="color:#e6db74">{</span>intento<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">try</span>:
</span></span><span style="display:flex;"><span>        enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">except</span> <span style="color:#a6e22e">Exception</span> <span style="color:#66d9ef">as</span> e:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">if</span> intento <span style="color:#f92672">&gt;=</span> MAX_INTENTOS:
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] error: </span><span style="color:#e6db74">{</span>e<span style="color:#e6db74">}</span><span style="color:#e6db74">; me rindo, va a fallidos&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>            canal<span style="color:#f92672">.</span>basic_publish(
</span></span><span style="display:flex;"><span>                exchange<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>                routing_key<span style="color:#f92672">=</span>COLA_FALLIDOS,
</span></span><span style="display:flex;"><span>                body<span style="color:#f92672">=</span>cuerpo,
</span></span><span style="display:flex;"><span>                properties<span style="color:#f92672">=</span>propiedades,
</span></span><span style="display:flex;"><span>            )
</span></span><span style="display:flex;"><span>            canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">else</span>:
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] error: </span><span style="color:#e6db74">{</span>e<span style="color:#e6db74">}</span><span style="color:#e6db74">; reintento en 5 s&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>            canal<span style="color:#f92672">.</span>basic_nack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag, requeue<span style="color:#f92672">=</span><span style="color:#66d9ef">False</span>)
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_ack(delivery_tag<span style="color:#f92672">=</span>metodo<span style="color:#f92672">.</span>delivery_tag)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>conexion <span style="color:#f92672">=</span> pika<span style="color:#f92672">.</span>BlockingConnection(pika<span style="color:#f92672">.</span>URLParameters(URL))
</span></span><span style="display:flex;"><span>canal <span style="color:#f92672">=</span> conexion<span style="color:#f92672">.</span>channel()
</span></span><span style="display:flex;"><span>declarar_colas(canal)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_qos(prefetch_count<span style="color:#f92672">=</span><span style="color:#ae81ff">1</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">False</span>)
</span></span><span style="display:flex;"><span>print(<span style="color:#e6db74">&#34;[worker] esperando mensajes&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>start_consuming()</span></span></code></pre></div>
</div>
<p>La diferencia clave con el arreglo malo está en una palabra: <code>requeue=False</code>. Antes el nack devolvía el mensaje a la misma cola; ahora lo rechaza, y rechazarlo activa el DLX, que lo manda a la cola de reintentos. El worker no sabe nada de esperas ni de temporizadores; solo cuenta cuántas veces ha pasado por ahí y decide.</p>
<p>Cuando se rinde, publica el mensaje tal cual (mismo cuerpo, mismas cabeceras, incluida <code>x-death</code>, que es útil para quien lo examine después) en <code>correos.fallidos</code>, y entonces sí hace ack del original.</p>
<p>Lanza el pedido de 2000 euros y otro normal justo detrás:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] pedido 513, intento 1
[worker] error: el servidor de correo ha rechazado el mensaje; reintento en 5 s
[worker] pedido 514, intento 1
[correo] confirmación del pedido 514 enviada
[worker] pedido 513, intento 2
[worker] error: el servidor de correo ha rechazado el mensaje; reintento en 5 s
[worker] pedido 513, intento 3
[worker] error: el servidor de correo ha rechazado el mensaje; me rindo, va a fallidos</code></pre>
</div>
<p>El 514 ha salido mientras el 513 esperaba su reintento: ya no bloquea a los demás. Tras tres intentos, el 513 está en <code>correos.fallidos</code>, donde en la interfaz web puedes abrirlo con <em>Get messages</em> y ver el cuerpo y la cabecera <code>x-death</code> con el historial. Lo que hagas con esa cola (una alerta, un reintento manual, un informe) ya es cosa de tu aplicación; lo importante es que el mensaje no se ha perdido y no está molestando.</p>
<h2 id="dónde-estamos">Dónde estamos <a class="ancla" href="#d%c3%b3nde-estamos" aria-label="Enlace a esta sección">#</a></h2>
<p>Cuatro fallos y lo que se ha aprendido de cada uno:</p>
<ul>
<li><code>auto_ack=True</code> pierde mensajes si el consumidor muere. Ack manual, después de hacer el trabajo.</li>
<li>Una excepción sin capturar tumba al worker y bloquea la cola con el mismo mensaje.</li>
<li>Capturar y reencolar en la misma cola es un bucle infinito.</li>
<li>Rechazar sin reencolar, con un DLX hacia una cola de espera que devuelve el mensaje a los pocos segundos, da reintentos con pausa gratis; y una cola de fallidos aparta lo que no tiene remedio.</li>
</ul>
<p>Queda un problema que se ha colado dos veces en esta entrada sin que lo señalara: con ack manual, el mensaje del fallo 1 se volvió a entregar con <code>redelivered=True</code>. ¿Y si el correo <strong>sí</strong> se había enviado y el worker murió justo antes del ack? Entonces se envía dos veces. Eso es la <a href="/posts/2026/colas-al-menos-una-vez-idempotencia/">tercera entrada</a>.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_9eeff6b6d153a2e8.png"/></item><item><title>Colas de mensajes para gente de síncrono</title><link>https://www.igalvan.es/posts/2026/colas-de-mensajes-para-gente-de-sincrono/</link><pubDate>Sun, 01 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/colas-de-mensajes-para-gente-de-sincrono/</guid><description><![CDATA[<p>Toda mi vida profesional ha sido síncrona: alguien pide, yo respondo, y hasta que no respondo nadie hace nada. HTTP, SQL, una llamada a función. Las colas de mensajes me parecieron durante mucho tiempo una complicación para gente con problemas que yo no tenía.</p>
<p>El problema sí lo tenía. Lo que no tenía era el vocabulario para reconocerlo. Esta serie es para quien esté en ese punto: tres entradas, la primera de teoría y montaje, y las otras dos rompiendo cosas a propósito para ver qué pasa, que es la única forma de entender para qué sirve una cola.</p>
<p>Reutilizo el laboratorio de la <a href="/series/graphql-para-gente-de-rest/">serie de GraphQL</a>: PostgreSQL en Podman con una tabla de usuarios y otra de pedidos, y una API REST en FastAPI. Si no la has leído no pasa nada; lo que hace falta está aquí.</p>
<p>El código está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-colas" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-colas</a>.</p>
<h2 id="el-problema-sin-colas">El problema, sin colas <a class="ancla" href="#el-problema-sin-colas" aria-label="Enlace a esta sección">#</a></h2>
<p>Un endpoint que crea un pedido. Al crearlo hay que mandar un correo de confirmación al usuario.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py (añadido)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> time
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> pydantic <span style="color:#f92672">import</span> BaseModel
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">NuevoPedido</span>(BaseModel):
</span></span><span style="display:flex;"><span>    usuario_id: int
</span></span><span style="display:flex;"><span>    total: float
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Simula un servidor de correo lento.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.post</span>(<span style="color:#e6db74">&#34;/pedidos&#34;</span>, status_code<span style="color:#f92672">=</span><span style="color:#ae81ff">201</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">crear_pedido</span>(nuevo: NuevoPedido):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        pedido <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            INSERT INTO pedidos (usuario_id, fecha, total, estado)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            VALUES (</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, CURRENT_DATE, </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, &#39;pendiente&#39;)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            RETURNING id, usuario_id, fecha, total, estado
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (nuevo<span style="color:#f92672">.</span>usuario_id, nuevo<span style="color:#f92672">.</span>total),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    enviar_correo(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> pedido</span></span></code></pre></div>
</div>
<p><code>enviar_correo</code> no manda nada: duerme dos segundos y escribe una línea. Es a propósito. Un servidor SMTP de verdad tarda, falla y a veces no contesta, y para el laboratorio quiero controlar todo eso con un <code>sleep</code> y, más adelante, con un <code>random()</code>.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~$ time curl -s -X POST localhost:8000/pedidos \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{&#34;usuario_id&#34;: 42, &#34;total&#34;: 19.9}&#39;
{&#34;id&#34;:501,&#34;usuario_id&#34;:42,&#34;fecha&#34;:&#34;2026-11-02&#34;,&#34;total&#34;:19.9,&#34;estado&#34;:&#34;pendiente&#34;}

real    0m2.031s</code></pre>
</div>
<p>Dos segundos. El pedido estaba guardado en la base de datos a los pocos milisegundos; el resto del tiempo el cliente ha estado esperando a que el correo saliera. Y hay un segundo problema peor que el primero: si <code>enviar_correo</code> lanza una excepción, el endpoint devuelve un 500 <strong>con el pedido ya insertado</strong>. El cliente ve un error, reintenta, y tienes dos pedidos.</p>
<p>Esto es lo que una cola resuelve: separar &ldquo;lo que tiene que pasar ahora&rdquo; (guardar el pedido y contestar) de &ldquo;lo que tiene que pasar, pero no necesariamente ahora ni necesariamente bien a la primera&rdquo; (el correo). Lo segundo se apunta en una cola y otro proceso lo hace cuando puede.</p>
<h2 id="las-piezas-traducidas">Las piezas, traducidas <a class="ancla" href="#las-piezas-traducidas" aria-label="Enlace a esta sección">#</a></h2>
<p>RabbitMQ tiene más vocabulario del que necesitas el primer día. Lo mínimo:</p>
<p><strong>Mensaje.</strong> Unos bytes y unas cabeceras. RabbitMQ no mira dentro; tú decides el formato. Aquí será JSON, igual que en HTTP.</p>
<p><strong>Cola.</strong> Una lista de mensajes esperando a que alguien los lea. Tiene nombre. Si vienes de HTTP, piensa en ella como una bandeja de entrada.</p>
<p><strong>Productor y consumidor.</strong> Quien escribe en la cola y quien lee de ella. No se conocen, no se esperan, pueden no estar vivos al mismo tiempo. Esto último es el punto: el productor publica aunque no haya ningún consumidor, y el consumidor lee lo que se publicó mientras estaba apagado.</p>
<p><strong>Exchange.</strong> La pieza que despista. Un productor nunca escribe en una cola directamente; escribe en un exchange con una clave (<code>routing_key</code>), y el exchange decide a qué colas va el mensaje según unas reglas (<em>bindings</em>). Sirve para repartir un mensaje a varias colas, o para enrutar por patrón. Hoy no vamos a usar nada de eso: el exchange por defecto (nombre vacío) entrega el mensaje a la cola que se llame igual que la <code>routing_key</code>. Es la forma de usar RabbitMQ como una cola simple, y es perfectamente legítima.</p>
<p><strong>Ack.</strong> La confirmación del consumidor de que ha terminado con un mensaje. Es la pieza más importante de toda la serie, y hoy la voy a usar mal a propósito.</p>
<p>Todo lo demás (exchanges de tipo <em>topic</em>, <em>fanout</em>, colas con TTL, <em>dead letter</em>, <em>quorum queues</em>) existe y es útil, pero no hace falta para entender para qué sirve una cola.</p>
<h2 id="rabbitmq-en-podman">RabbitMQ en Podman <a class="ancla" href="#rabbitmq-en-podman" aria-label="Enlace a esta sección">#</a></h2>
<p>Al <code>compose.yaml</code> del laboratorio le añado un servicio:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#75715e"># compose.yaml (añadido)</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">rabbitmq</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">image</span>: <span style="color:#ae81ff">docker.io/library/rabbitmq:4-management</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">environment</span>:
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">RABBITMQ_DEFAULT_USER</span>: <span style="color:#ae81ff">lab</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">RABBITMQ_DEFAULT_PASS</span>: <span style="color:#ae81ff">lab</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ports</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#e6db74">&#34;5672:5672&#34;</span>
</span></span><span style="display:flex;"><span>      - <span style="color:#e6db74">&#34;15672:15672&#34;</span></span></span></code></pre></div>
</div>
<p>La etiqueta <code>-management</code> trae la interfaz web, que va a ser nuestro instrumento de medida en esta serie, como lo fue <code>log_statement</code> en la anterior. El usuario <code>lab</code> lo defino yo porque el <code>guest</code> que viene de serie solo acepta conexiones desde <code>localhost</code> <em>del contenedor</em>, y con <a href="/posts/2026/podman-rootless-sin-sudo-ni-docker/">Podman rootless</a> las conexiones desde el anfitrión no cuentan como tal; es la primera piedra con la que tropieza todo el mundo.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ podman compose up -d rabbitmq
ignacio@zeus:~/lab-colas$ podman compose logs rabbitmq | grep -i &#39;server startup complete&#39;
rabbitmq  | 2026-11-02 17:40:12.118 [info] &lt;0.690.0&gt; Server startup complete; 4 plugins started.</code></pre>
</div>
<p>Y la interfaz, en <code>http://localhost:15672</code>, con <code>lab</code>/<code>lab</code>. Déjala abierta en la pestaña <em>Queues</em>.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ pip install pika</code></pre>
</div>
<p><code>pika</code> es el cliente de Python que mantiene el propio equipo de RabbitMQ. Es síncrono y bloqueante, que es exactamente lo que quiero para que el código se lea de arriba abajo.</p>
<h2 id="el-productor">El productor <a class="ancla" href="#el-productor" aria-label="Enlace a esta sección">#</a></h2>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># cola.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> pika
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>URL <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;amqp://lab:lab@localhost:5672/&#34;</span>
</span></span><span style="display:flex;"><span>COLA <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;correos&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">publicar</span>(mensaje: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    conexion <span style="color:#f92672">=</span> pika<span style="color:#f92672">.</span>BlockingConnection(pika<span style="color:#f92672">.</span>URLParameters(URL))
</span></span><span style="display:flex;"><span>    canal <span style="color:#f92672">=</span> conexion<span style="color:#f92672">.</span>channel()
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>queue_declare(queue<span style="color:#f92672">=</span>COLA, durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    canal<span style="color:#f92672">.</span>basic_publish(
</span></span><span style="display:flex;"><span>        exchange<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>        routing_key<span style="color:#f92672">=</span>COLA,
</span></span><span style="display:flex;"><span>        body<span style="color:#f92672">=</span>json<span style="color:#f92672">.</span>dumps(mensaje, default<span style="color:#f92672">=</span>str),
</span></span><span style="display:flex;"><span>        properties<span style="color:#f92672">=</span>pika<span style="color:#f92672">.</span>BasicProperties(delivery_mode<span style="color:#f92672">=</span><span style="color:#ae81ff">2</span>),
</span></span><span style="display:flex;"><span>    )
</span></span><span style="display:flex;"><span>    conexion<span style="color:#f92672">.</span>close()</span></span></code></pre></div>
</div>
<p>Línea a línea:</p>
<ul>
<li><code>queue_declare</code> crea la cola si no existe y no hace nada si existe. Es idempotente, y es costumbre que tanto el productor como el consumidor la declaren, para que dé igual cuál arranca primero. <code>durable=True</code> hace que la cola sobreviva a un reinicio de RabbitMQ.</li>
<li><code>exchange=&quot;&quot;</code> es el exchange por defecto, y <code>routing_key=COLA</code> hace que el mensaje caiga en la cola <code>correos</code>.</li>
<li><code>delivery_mode=2</code> marca el mensaje como persistente: se escribe a disco. Sin esto, un reinicio del bróker se lleva los mensajes aunque la cola sea durable. Cola durable y mensaje persistente son dos cosas distintas, y hacen falta las dos.</li>
<li><code>default=str</code> en el <code>json.dumps</code> es para que el <code>date</code> y el <code>Decimal</code> que vienen de PostgreSQL no rompan la serialización.</li>
</ul>
<p>Abrir y cerrar una conexión por mensaje es un despilfarro; en un servidor de verdad la conexión se mantiene abierta. Lo dejo así para que no haya nada que explicar sobre el ciclo de vida de la conexión.</p>
<p>Y el endpoint, en vez de enviar el correo, publica:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> cola <span style="color:#f92672">import</span> publicar
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.post</span>(<span style="color:#e6db74">&#34;/pedidos&#34;</span>, status_code<span style="color:#f92672">=</span><span style="color:#ae81ff">201</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">crear_pedido</span>(nuevo: NuevoPedido):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        pedido <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            INSERT INTO pedidos (usuario_id, fecha, total, estado)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            VALUES (</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, CURRENT_DATE, </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">, &#39;pendiente&#39;)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            RETURNING id, usuario_id, fecha, total, estado
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (nuevo<span style="color:#f92672">.</span>usuario_id, nuevo<span style="color:#f92672">.</span>total),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    publicar(pedido)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> pedido</span></span></code></pre></div>
</div>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~$ time curl -s -X POST localhost:8000/pedidos \
  -H &#39;Content-Type: application/json&#39; \
  -d &#39;{&#34;usuario_id&#34;: 42, &#34;total&#34;: 19.9}&#39;
{&#34;id&#34;:502,&#34;usuario_id&#34;:42,&#34;fecha&#34;:&#34;2026-11-02&#34;,&#34;total&#34;:19.9,&#34;estado&#34;:&#34;pendiente&#34;}

real    0m0.047s</code></pre>
</div>
<p>De dos segundos a cuarenta y pico milisegundos. El correo no se ha enviado todavía; lo que se ha hecho es dejar constancia de que hay que enviarlo. En la interfaz web, la cola <code>correos</code> tiene un mensaje en <em>Ready</em>.</p>
<p>Lanza cuatro o cinco pedidos más. Se van acumulando. No hay nadie leyendo, y a RabbitMQ le da igual: ese es el desacoplamiento del que hablaba. El productor ha terminado su trabajo aunque el consumidor no exista aún.</p>
<h2 id="el-consumidor">El consumidor <a class="ancla" href="#el-consumidor" aria-label="Enlace a esta sección">#</a></h2>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># worker.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> json
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> time
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> pika
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> cola <span style="color:#f92672">import</span> COLA, URL
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">enviar_correo</span>(pedido: dict) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">2</span>)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[correo] confirmación del pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74"> enviada&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">procesar</span>(canal, metodo, propiedades, cuerpo: bytes) <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    pedido <span style="color:#f92672">=</span> json<span style="color:#f92672">.</span>loads(cuerpo)
</span></span><span style="display:flex;"><span>    print(<span style="color:#e6db74">f</span><span style="color:#e6db74">&#34;[worker] recibido pedido </span><span style="color:#e6db74">{</span>pedido[<span style="color:#e6db74">&#39;id&#39;</span>]<span style="color:#e6db74">}</span><span style="color:#e6db74">&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>    enviar_correo(pedido)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>conexion <span style="color:#f92672">=</span> pika<span style="color:#f92672">.</span>BlockingConnection(pika<span style="color:#f92672">.</span>URLParameters(URL))
</span></span><span style="display:flex;"><span>canal <span style="color:#f92672">=</span> conexion<span style="color:#f92672">.</span>channel()
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>queue_declare(queue<span style="color:#f92672">=</span>COLA, durable<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>basic_consume(queue<span style="color:#f92672">=</span>COLA, on_message_callback<span style="color:#f92672">=</span>procesar, auto_ack<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>print(<span style="color:#e6db74">&#34;[worker] esperando mensajes&#34;</span>, flush<span style="color:#f92672">=</span><span style="color:#66d9ef">True</span>)
</span></span><span style="display:flex;"><span>canal<span style="color:#f92672">.</span>start_consuming()</span></span></code></pre></div>
</div>
<p><code>basic_consume</code> registra <code>procesar</code> como la función que RabbitMQ llamará por cada mensaje, y <code>start_consuming</code> se queda en bucle esperando. <code>auto_ack=True</code> le dice a RabbitMQ que dé el mensaje por entregado en cuanto lo manda al consumidor, antes de que <code>procesar</code> haga nada. Guárdate esa frase.</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] recibido pedido 502
[correo] confirmación del pedido 502 enviada
[worker] recibido pedido 503
[correo] confirmación del pedido 503 enviada
[worker] recibido pedido 504
...</code></pre>
</div>
<p>Los mensajes que se acumularon mientras no había consumidor salen todos seguidos, de dos en dos segundos, y en la interfaz web la cola vuelve a cero. Si ahora lanzas otro pedido con el worker vivo, aparece en el log del worker medio segundo después y el <code>curl</code> sigue tardando cuarenta milisegundos.</p>
<p>Dos terminales más y tienes dos workers consumiendo de la misma cola: RabbitMQ reparte los mensajes entre ellos por turnos. Escalar el envío de correos es arrancar otro proceso; el endpoint ni se entera.</p>
<h2 id="dónde-estamos">Dónde estamos <a class="ancla" href="#d%c3%b3nde-estamos" aria-label="Enlace a esta sección">#</a></h2>
<p>Hemos separado el pedido del correo, el endpoint responde en milisegundos, los correos se envían cuando se puede y añadir capacidad es arrancar otro worker. Todo lo que promete la portada de cualquier bróker de mensajes.</p>
<p>Y hay un <code>auto_ack=True</code> ahí en medio que lo echa todo a perder, pero solo cuando algo falla. En la <a href="/posts/2026/colas-cuando-el-consumidor-se-cae/">siguiente entrada</a> mato al worker a mitad de un correo y miro qué ha pasado con el mensaje.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_77670c3fdda90729.png"/></item><item><title>El N+1 en el log, DataLoader y lo que pasa con la caché</title><link>https://www.igalvan.es/posts/2026/graphql-n-mas-1-dataloader-cache/</link><pubDate>Fri, 30 Oct 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/graphql-n-mas-1-dataloader-cache/</guid><description><![CDATA[<p>Tercera y última entrada de la serie. En la <a href="/posts/2026/graphql-para-gente-de-rest/">primera</a> está la teoría y en la <a href="/posts/2026/graphql-laboratorio-rest-vs-graphql/">segunda</a> el laboratorio: PostgreSQL con dos tablas, una API REST en FastAPI y una API GraphQL en Strawberry, las dos sobre el mismo <code>db.py</code>, y la base de datos escribiendo en su log cada consulta que recibe.</p>
<p>Allí comparé la ficha de un usuario y GraphQL salía ganando. Ahora cambio la pantalla.</p>
<h2 id="segunda-pantalla-el-listado">Segunda pantalla: el listado <a class="ancla" href="#segunda-pantalla-el-listado" aria-label="Enlace a esta sección">#</a></h2>
<p>El caso de uso: una tabla con cien usuarios, y para cada uno el importe de sus tres últimos pedidos. Es la pantalla de &ldquo;listado con un poco de detalle&rdquo; que tiene cualquier aplicación.</p>
<h3 id="en-rest">En REST <a class="ancla" href="#en-rest" aria-label="Enlace a esta sección">#</a></h3>
<p>En REST, para esta pantalla, no tengo nada. <code>/usuarios/{id}</code> y <code>/usuarios/{id}/pedidos</code> me obligan a hacer una petición para la lista y cien más para los pedidos, lo cual es el N+1 <strong>en HTTP</strong>, que es aún peor que en SQL.</p>
<p>Así que hago lo que hace todo el mundo: un endpoint para la pantalla.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py (añadido)</span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.get</span>(<span style="color:#e6db74">&#34;/usuarios&#34;</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuarios</span>(
</span></span><span style="display:flex;"><span>    primeros: int <span style="color:#f92672">=</span> Query(<span style="color:#ae81ff">10</span>, ge<span style="color:#f92672">=</span><span style="color:#ae81ff">1</span>, le<span style="color:#f92672">=</span><span style="color:#ae81ff">100</span>),
</span></span><span style="display:flex;"><span>    pedidos: int <span style="color:#f92672">=</span> Query(<span style="color:#ae81ff">3</span>, ge<span style="color:#f92672">=</span><span style="color:#ae81ff">0</span>, le<span style="color:#f92672">=</span><span style="color:#ae81ff">10</span>),
</span></span><span style="display:flex;"><span>):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            SELECT u.id, u.nombre,
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                   COALESCE(
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                     json_agg(
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                       json_build_object(&#39;fecha&#39;, p.fecha, &#39;total&#39;, p.total)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                       ORDER BY p.fecha DESC
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                     ) FILTER (WHERE p.id IS NOT NULL),
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                     &#39;[]&#39;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                   ) AS pedidos
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            FROM usuarios u
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            LEFT JOIN LATERAL (
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              SELECT * FROM pedidos
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              WHERE usuario_id = u.id
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              ORDER BY fecha DESC
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              LIMIT </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ) p ON true
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            GROUP BY u.id
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ORDER BY u.id
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            LIMIT </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (pedidos, primeros),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchall()</span></span></code></pre></div>
</div>
<p>Una sola consulta. El <code>LATERAL</code> es el truco de PostgreSQL para &ldquo;los N últimos de cada uno&rdquo;, y el <code>json_agg</code> monta la lista de pedidos ya en la base de datos. Es un endpoint muy bueno y muy a medida: devuelve exactamente lo que quiere esta pantalla, y si mañana otra pantalla quiere el <code>estado</code> de los pedidos, hay que tocar el SQL.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@zeus:~$ curl -s <span style="color:#e6db74">&#39;localhost:8000/usuarios?primeros=100&amp;pedidos=3&#39;</span> | jq <span style="color:#e6db74">&#39;.[0]&#39;</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;id&#34;</span>: 1,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;nombre&#34;</span>: <span style="color:#e6db74">&#34;Usuario 1&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;pedidos&#34;</span>: <span style="color:#f92672">[</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2026-06-02&#34;</span>, <span style="color:#e6db74">&#34;total&#34;</span>: 44.1 <span style="color:#f92672">}</span>,
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2025-11-19&#34;</span>, <span style="color:#e6db74">&#34;total&#34;</span>: 173.25 <span style="color:#f92672">}</span>,
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2025-03-08&#34;</span>, <span style="color:#e6db74">&#34;total&#34;</span>: 12.9 <span style="color:#f92672">}</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">]</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">}</span></span></span></code></pre></div>
</div>
<p>Y en el log de PostgreSQL:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>LOG:  statement: SELECT u.id, u.nombre, COALESCE<span style="color:#f92672">(</span>json_agg<span style="color:#f92672">(</span>...<span style="color:#f92672">))</span> AS pedidos FROM usuarios u LEFT JOIN LATERAL <span style="color:#f92672">(</span>...<span style="color:#f92672">)</span> ...</span></span></code></pre></div>
</div>
<p>Una línea.</p>
<h3 id="en-graphql-tal-cual-estaba">En GraphQL, tal cual estaba <a class="ancla" href="#en-graphql-tal-cual-estaba" aria-label="Enlace a esta sección">#</a></h3>
<p>En GraphQL no hay que escribir un endpoint nuevo. Solo necesito una query que devuelva varios usuarios; el campo <code>pedidos</code> ya existe en el tipo <code>Usuario</code>.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_graphql/main.py (añadido a Query)</span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">@strawberry.field</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuarios</span>(self, primeros: int <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>) <span style="color:#f92672">-&gt;</span> list[Usuario]:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>            filas <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>                <span style="color:#e6db74">&#34;SELECT * FROM usuarios ORDER BY id LIMIT </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">&#34;</span>, (primeros,)
</span></span><span style="display:flex;"><span>            )<span style="color:#f92672">.</span>fetchall()
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> [Usuario(<span style="color:#f92672">**</span>f) <span style="color:#66d9ef">for</span> f <span style="color:#f92672">in</span> filas]</span></span></code></pre></div>
</div>
<p>Y el cliente pide:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@zeus:~$ curl -s localhost:8001/graphql <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>  -H <span style="color:#e6db74">&#39;Content-Type: application/json&#39;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>  -d <span style="color:#e6db74">&#39;{&#34;query&#34;: &#34;{ usuarios(primeros: 100) { nombre pedidos(ultimos: 3) { total } } }&#34;}&#39;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>  | jq <span style="color:#e6db74">&#39;.data.usuarios[0]&#39;</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;nombre&#34;</span>: <span style="color:#e6db74">&#34;Usuario 1&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;pedidos&#34;</span>: <span style="color:#f92672">[</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;total&#34;</span>: <span style="color:#e6db74">&#34;44.10&#34;</span> <span style="color:#f92672">}</span>,
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;total&#34;</span>: <span style="color:#e6db74">&#34;173.25&#34;</span> <span style="color:#f92672">}</span>,
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;total&#34;</span>: <span style="color:#e6db74">&#34;12.90&#34;</span> <span style="color:#f92672">}</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">]</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">}</span></span></span></code></pre></div>
</div>
<p>Funciona, la respuesta es perfecta, el cliente ha obtenido exactamente lo que quería sin que yo escribiera un endpoint. Ahora el log:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>LOG:  statement: SELECT * FROM usuarios ORDER BY id LIMIT <span style="color:#ae81ff">100</span>
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT id, fecha, total, estado FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">1</span> ORDER BY fecha DESC LIMIT <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT id, fecha, total, estado FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">2</span> ORDER BY fecha DESC LIMIT <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT id, fecha, total, estado FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">3</span> ORDER BY fecha DESC LIMIT <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span>...
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT id, fecha, total, estado FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">100</span> ORDER BY fecha DESC LIMIT <span style="color:#ae81ff">3</span></span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@zeus:~/lab-graphql$ podman compose logs db | grep -c <span style="color:#e6db74">&#39;FROM pedidos WHERE usuario_id&#39;</span>
</span></span><span style="display:flex;"><span><span style="color:#ae81ff">100</span></span></span></code></pre></div>
</div>
<p>Ciento una consultas. Esto es el N+1, y conviene entender por qué ha pasado, porque no es un bug: es el diseño de los resolvers funcionando como se espera. <code>Query.usuarios</code> resolvió la lista con una consulta. Después Strawberry recorrió los cien usuarios, y para cada uno, como el cliente había pedido <code>pedidos</code>, llamó a <code>Usuario.pedidos</code>, que hace su consulta con <code>self.id</code>. Cien veces. El resolver de <code>pedidos</code> no sabe que hay otros noventa y nueve como él en marcha; solo sabe resolver los pedidos de un usuario. (Si quieres ver cómo se lee lo que hace PostgreSQL con cada una de esas consultas, tengo <a href="/posts/2026/explain-analyze-para-humanos/">una entrada sobre EXPLAIN ANALYZE</a>.)</p>
<p>En REST esto no me pasó porque <strong>yo</strong> escribí la consulta para la pantalla. En GraphQL la pantalla la ha inventado el cliente, y el servidor la ha resuelto de la única manera que sabía: campo a campo.</p>
<h2 id="dataloader">DataLoader <a class="ancla" href="#dataloader" aria-label="Enlace a esta sección">#</a></h2>
<p>La solución es un patrón, no una librería concreta, aunque Strawberry trae una implementación. La idea: en vez de que <code>Usuario.pedidos</code> haga su consulta en el acto, le pide los pedidos a un <em>loader</em> y se queda esperando. El loader no consulta nada hasta que todos los resolvers de ese ciclo han hecho su petición; entonces junta las cien claves y lanza <strong>una</strong> consulta para todas. Después reparte los resultados a cada resolver que esperaba.</p>
<p>Para que eso funcione los resolvers tienen que ser asíncronos (si no, no hay &ldquo;quedarse esperando&rdquo;), así que <code>Usuario.pedidos</code> pasa a <code>async</code>.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_graphql/main.py (versión con DataLoader)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> datetime
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> decimal
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> strawberry
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> fastapi <span style="color:#f92672">import</span> FastAPI
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> strawberry.dataloader <span style="color:#f92672">import</span> DataLoader
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> strawberry.fastapi <span style="color:#f92672">import</span> GraphQLRouter
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> db <span style="color:#f92672">import</span> conectar
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@strawberry.type</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">Pedido</span>:
</span></span><span style="display:flex;"><span>    id: int
</span></span><span style="display:flex;"><span>    fecha: datetime<span style="color:#f92672">.</span>date
</span></span><span style="display:flex;"><span>    total: decimal<span style="color:#f92672">.</span>Decimal
</span></span><span style="display:flex;"><span>    estado: str
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">async</span> <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">cargar_pedidos</span>(claves: list[tuple[int, int]]) <span style="color:#f92672">-&gt;</span> list[list[Pedido]]:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Recibe pares (usuario_id, ultimos) y devuelve, en el mismo orden,
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">    la lista de pedidos de cada uno.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    ids <span style="color:#f92672">=</span> [usuario_id <span style="color:#66d9ef">for</span> usuario_id, _ <span style="color:#f92672">in</span> claves]
</span></span><span style="display:flex;"><span>    tope <span style="color:#f92672">=</span> max(ultimos <span style="color:#66d9ef">for</span> _, ultimos <span style="color:#f92672">in</span> claves)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        filas <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            SELECT id, usuario_id, fecha, total, estado
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            FROM (
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              SELECT *,
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                     row_number() OVER (
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                       PARTITION BY usuario_id ORDER BY fecha DESC
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                     ) AS n
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              FROM pedidos
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">              WHERE usuario_id = ANY(</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ) t
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            WHERE n &lt;= </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ORDER BY usuario_id, fecha DESC
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (ids, tope),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchall()
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    por_usuario: dict[int, list[Pedido]] <span style="color:#f92672">=</span> {}
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">for</span> f <span style="color:#f92672">in</span> filas:
</span></span><span style="display:flex;"><span>        uid <span style="color:#f92672">=</span> f<span style="color:#f92672">.</span>pop(<span style="color:#e6db74">&#34;usuario_id&#34;</span>)
</span></span><span style="display:flex;"><span>        por_usuario<span style="color:#f92672">.</span>setdefault(uid, [])<span style="color:#f92672">.</span>append(Pedido(<span style="color:#f92672">**</span>f))
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> [por_usuario<span style="color:#f92672">.</span>get(uid, [])[:ultimos] <span style="color:#66d9ef">for</span> uid, ultimos <span style="color:#f92672">in</span> claves]
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@strawberry.type</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">Usuario</span>:
</span></span><span style="display:flex;"><span>    id: int
</span></span><span style="display:flex;"><span>    nombre: str
</span></span><span style="display:flex;"><span>    email: str
</span></span><span style="display:flex;"><span>    direccion: str <span style="color:#f92672">|</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>    telefono: str <span style="color:#f92672">|</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>    fecha_alta: datetime<span style="color:#f92672">.</span>date
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">@strawberry.field</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">async</span> <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">pedidos</span>(self, info: strawberry<span style="color:#f92672">.</span>Info, ultimos: int <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>) <span style="color:#f92672">-&gt;</span> list[Pedido]:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> <span style="color:#66d9ef">await</span> info<span style="color:#f92672">.</span>context[<span style="color:#e6db74">&#34;pedidos&#34;</span>]<span style="color:#f92672">.</span>load((self<span style="color:#f92672">.</span>id, ultimos))
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@strawberry.type</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">Query</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">@strawberry.field</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuario</span>(self, id: int) <span style="color:#f92672">-&gt;</span> Usuario <span style="color:#f92672">|</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>            fila <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>                <span style="color:#e6db74">&#34;SELECT * FROM usuarios WHERE id = </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">&#34;</span>, (id,)
</span></span><span style="display:flex;"><span>            )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> Usuario(<span style="color:#f92672">**</span>fila) <span style="color:#66d9ef">if</span> fila <span style="color:#66d9ef">else</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">@strawberry.field</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuarios</span>(self, primeros: int <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>) <span style="color:#f92672">-&gt;</span> list[Usuario]:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>            filas <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>                <span style="color:#e6db74">&#34;SELECT * FROM usuarios ORDER BY id LIMIT </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">&#34;</span>, (primeros,)
</span></span><span style="display:flex;"><span>            )<span style="color:#f92672">.</span>fetchall()
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> [Usuario(<span style="color:#f92672">**</span>f) <span style="color:#66d9ef">for</span> f <span style="color:#f92672">in</span> filas]
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">async</span> <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">contexto</span>():
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> {<span style="color:#e6db74">&#34;pedidos&#34;</span>: DataLoader(load_fn<span style="color:#f92672">=</span>cargar_pedidos)}
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>schema <span style="color:#f92672">=</span> strawberry<span style="color:#f92672">.</span>Schema(query<span style="color:#f92672">=</span>Query)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>app <span style="color:#f92672">=</span> FastAPI()
</span></span><span style="display:flex;"><span>app<span style="color:#f92672">.</span>include_router(
</span></span><span style="display:flex;"><span>    GraphQLRouter(schema, context_getter<span style="color:#f92672">=</span>contexto), prefix<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/graphql&#34;</span>
</span></span><span style="display:flex;"><span>)</span></span></code></pre></div>
</div>
<p>Tres cosas que mirar:</p>
<ul>
<li><strong><code>cargar_pedidos</code> recibe una lista de claves y devuelve una lista de resultados en el mismo orden.</strong> Es el contrato de todo DataLoader. La clave es <code>(usuario_id, ultimos)</code> porque el campo tiene un argumento; si fuera solo <code>usuario_id</code>, un cliente que pidiera <code>ultimos: 3</code> para unos y <code>ultimos: 5</code> para otros rompería el agrupado.</li>
<li><strong>La consulta es la del <code>LATERAL</code> de REST, resuelta con una función de ventana.</strong> <code>row_number() OVER (PARTITION BY usuario_id ORDER BY fecha DESC)</code> numera los pedidos de cada usuario del más reciente al más antiguo, y <code>n &lt;= tope</code> se queda con los primeros. <code>ANY(%s)</code> recibe la lista de ids como un array de PostgreSQL; psycopg hace la conversión.</li>
<li><strong>El loader se crea en <code>contexto()</code>, una vez por petición HTTP.</strong> Si fuera global, cachearía resultados entre peticiones y servirías datos viejos. Ese es el error típico al empezar con DataLoader.</li>
</ul>
<p>El cliente no cambia nada. La misma consulta de antes, y el log:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>LOG:  statement: SELECT * FROM usuarios ORDER BY id LIMIT <span style="color:#ae81ff">100</span>
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT id, usuario_id, fecha, total, estado FROM <span style="color:#f92672">(</span>SELECT *, row_number<span style="color:#f92672">()</span> OVER <span style="color:#f92672">(</span>...<span style="color:#f92672">)</span> AS n FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> ANY<span style="color:#f92672">(</span><span style="color:#e6db74">&#39;{1,2,3,...,100}&#39;</span><span style="color:#f92672">))</span> t WHERE n &lt;<span style="color:#f92672">=</span> <span style="color:#ae81ff">3</span> ORDER BY usuario_id, fecha DESC</span></span></code></pre></div>
</div>
<p>Dos consultas. Hemos vuelto al nivel de REST, con una diferencia que vale la pena notar: el endpoint REST servía a <em>esta</em> pantalla, y el loader sirve a cualquier consulta que pase por <code>Usuario.pedidos</code>, venga de donde venga. Es más trabajo la primera vez y menos las siguientes.</p>
<p>Y una pega que no voy a esconder: <code>cargar_pedidos</code> es <code>async</code> pero llama a psycopg en modo síncrono, así que bloquea el bucle de eventos mientras consulta. Para el laboratorio da igual; en un servidor real usarías <code>psycopg.AsyncConnection</code> o un <em>pool</em>. Lo dejo así para que el código sea comparable con el de REST línea a línea.</p>
<h2 id="la-caché-en-treinta-segundos">La caché, en treinta segundos <a class="ancla" href="#la-cach%c3%a9-en-treinta-segundos" aria-label="Enlace a esta sección">#</a></h2>
<p>Lo último que quedaba pendiente de la primera entrada. En REST, el endpoint de un usuario es un <code>GET</code> a una URL, y cachearlo es una cabecera:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py (modificado)</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> fastapi <span style="color:#f92672">import</span> Response
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.get</span>(<span style="color:#e6db74">&#34;/usuarios/</span><span style="color:#e6db74">{id}</span><span style="color:#e6db74">&#34;</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuario</span>(id: int, response: Response):
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">...</span>
</span></span><span style="display:flex;"><span>    response<span style="color:#f92672">.</span>headers[<span style="color:#e6db74">&#34;Cache-Control&#34;</span>] <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;public, max-age=60&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> fila</span></span></code></pre></div>
</div>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@zeus:~$ curl -sI localhost:8000/usuarios/42 | grep -i cache
</span></span><span style="display:flex;"><span>cache-control: public, max-age<span style="color:#f92672">=</span><span style="color:#ae81ff">60</span></span></span></code></pre></div>
</div>
<p>A partir de aquí, cualquier proxy inverso, CDN o navegador que haya por el camino puede servir ese usuario durante un minuto sin preguntar al servidor. No has escrito nada.</p>
<p>En GraphQL, la misma ficha es un <code>POST /graphql</code> con la consulta en el cuerpo. Para un proxy, es una petición opaca e idéntica a todas las demás; no hay URL que identifique el recurso ni método que diga que es una lectura. <code>Cache-Control</code> no sirve de nada, y lo que te queda son las alternativas que mencioné en la primera entrada: consultas persistidas (el cliente manda un identificador por <code>GET</code> en vez de la consulta entera, y entonces sí hay algo cacheable), caché normalizada en el cliente, o caché de respuestas en el propio servidor. Todas funcionan; ninguna viene de serie.</p>
<h2 id="lo-que-ha-enseñado-el-laboratorio">Lo que ha enseñado el laboratorio <a class="ancla" href="#lo-que-ha-ense%c3%b1ado-el-laboratorio" aria-label="Enlace a esta sección">#</a></h2>
<p>Con dos tablas y dos pantallas:</p>
<ul>
<li>Para una ficha, GraphQL gana en HTTP (una petición, respuesta a medida) y empata en la base de datos.</li>
<li>Para un listado, REST gana en la base de datos porque el endpoint lo escribiste tú para esa pantalla; GraphQL pierde de serie (101 consultas) y empata con DataLoader, a cambio de más código en el servidor y de que el patrón se reutilice.</li>
<li>La caché HTTP la tiene REST gratis y GraphQL no la tiene.</li>
</ul>
<p>Nada de esto es nuevo si leíste la primera entrada, pero ahora las frases tienen una línea de log detrás. Y la conclusión sigue siendo la misma: GraphQL no es mejor ni peor que REST; mueve el trabajo de sitio. De escribir endpoints a escribir loaders, de la caché HTTP a la caché de aplicación, de decidir tú la forma de los datos a defenderte de la forma que decida el cliente. Si ese cambio te conviene, adelante. Si no, REST sigue estando muy bien.</p>
<p>El código de las tres entradas está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-graphql" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-graphql</a>.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_8d929e04e945a9b.png"/></item><item><title>Un laboratorio para comparar REST y GraphQL con los mismos datos</title><link>https://www.igalvan.es/posts/2026/graphql-laboratorio-rest-vs-graphql/</link><pubDate>Thu, 29 Oct 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/graphql-laboratorio-rest-vs-graphql/</guid><description><![CDATA[<p>En la <a href="/posts/2026/graphql-para-gente-de-rest/">entrada anterior</a> conté la teoría. Ahora toca verla. Voy a montar una base de datos pequeña, exponer los mismos datos con una API REST y con una API GraphQL, y comparar lo que pide el cliente, lo que recibe y lo que le llega a PostgreSQL por detrás.</p>
<p>Esta entrada es el montaje y la primera comparación, la amable. En la siguiente viene el N+1, que es donde se pone interesante.</p>
<p>El código completo está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-graphql" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-graphql</a>.</p>
<h2 id="los-datos">Los datos <a class="ancla" href="#los-datos" aria-label="Enlace a esta sección">#</a></h2>
<p>Dos tablas: usuarios y pedidos. Nada más, porque con dos tablas ya se ven todos los problemas que quiero enseñar.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-sql" data-lang="sql"><span style="display:flex;"><span><span style="color:#75715e">-- init.sql
</span></span></span><span style="display:flex;"><span><span style="color:#66d9ef">CREATE</span> <span style="color:#66d9ef">TABLE</span> usuarios (
</span></span><span style="display:flex;"><span>  id         serial <span style="color:#66d9ef">PRIMARY</span> <span style="color:#66d9ef">KEY</span>,
</span></span><span style="display:flex;"><span>  nombre     text <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span>,
</span></span><span style="display:flex;"><span>  email      text <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span>,
</span></span><span style="display:flex;"><span>  direccion  text,
</span></span><span style="display:flex;"><span>  telefono   text,
</span></span><span style="display:flex;"><span>  fecha_alta date <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span>
</span></span><span style="display:flex;"><span>);
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">CREATE</span> <span style="color:#66d9ef">TABLE</span> pedidos (
</span></span><span style="display:flex;"><span>  id         serial <span style="color:#66d9ef">PRIMARY</span> <span style="color:#66d9ef">KEY</span>,
</span></span><span style="display:flex;"><span>  usuario_id int <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span> <span style="color:#66d9ef">REFERENCES</span> usuarios(id),
</span></span><span style="display:flex;"><span>  fecha      date <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span>,
</span></span><span style="display:flex;"><span>  total      numeric(<span style="color:#ae81ff">10</span>,<span style="color:#ae81ff">2</span>) <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span>,
</span></span><span style="display:flex;"><span>  estado     text <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span>
</span></span><span style="display:flex;"><span>);
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">INSERT</span> <span style="color:#66d9ef">INTO</span> usuarios (nombre, email, direccion, telefono, fecha_alta)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">SELECT</span>
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#39;Usuario &#39;</span> <span style="color:#f92672">||</span> i,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#39;usuario&#39;</span> <span style="color:#f92672">||</span> i <span style="color:#f92672">||</span> <span style="color:#e6db74">&#39;@example.org&#39;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#39;Calle Mayor, &#39;</span> <span style="color:#f92672">||</span> i,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#39;600&#39;</span> <span style="color:#f92672">||</span> lpad(i::text, <span style="color:#ae81ff">6</span>, <span style="color:#e6db74">&#39;0&#39;</span>),
</span></span><span style="display:flex;"><span>  date <span style="color:#e6db74">&#39;2024-01-01&#39;</span> <span style="color:#f92672">+</span> i <span style="color:#f92672">*</span> <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">FROM</span> generate_series(<span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">100</span>) <span style="color:#66d9ef">AS</span> i;
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">INSERT</span> <span style="color:#66d9ef">INTO</span> pedidos (usuario_id, fecha, total, estado)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">SELECT</span>
</span></span><span style="display:flex;"><span>  <span style="color:#ae81ff">1</span> <span style="color:#f92672">+</span> (random() <span style="color:#f92672">*</span> <span style="color:#ae81ff">99</span>)::int,
</span></span><span style="display:flex;"><span>  date <span style="color:#e6db74">&#39;2025-01-01&#39;</span> <span style="color:#f92672">+</span> (random() <span style="color:#f92672">*</span> <span style="color:#ae81ff">600</span>)::int,
</span></span><span style="display:flex;"><span>  round((<span style="color:#ae81ff">5</span> <span style="color:#f92672">+</span> random() <span style="color:#f92672">*</span> <span style="color:#ae81ff">200</span>)::numeric, <span style="color:#ae81ff">2</span>),
</span></span><span style="display:flex;"><span>  (ARRAY[<span style="color:#e6db74">&#39;pendiente&#39;</span>, <span style="color:#e6db74">&#39;enviado&#39;</span>, <span style="color:#e6db74">&#39;entregado&#39;</span>])[<span style="color:#ae81ff">1</span> <span style="color:#f92672">+</span> (random() <span style="color:#f92672">*</span> <span style="color:#ae81ff">2</span>)::int]
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">FROM</span> generate_series(<span style="color:#ae81ff">1</span>, <span style="color:#ae81ff">500</span>);</span></span></code></pre></div>
</div>
<p>Cien usuarios y quinientos pedidos repartidos al azar. Los usuarios tienen seis columnas a propósito: la gracia del over-fetching es que haya cosas que sobren.</p>
<h2 id="postgresql-en-podman">PostgreSQL en Podman <a class="ancla" href="#postgresql-en-podman" aria-label="Enlace a esta sección">#</a></h2>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-yaml" data-lang="yaml"><span style="display:flex;"><span><span style="color:#75715e"># compose.yaml</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">services</span>:
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">db</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">image</span>: <span style="color:#ae81ff">docker.io/library/postgres:17</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">environment</span>:
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">POSTGRES_USER</span>: <span style="color:#ae81ff">lab</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">POSTGRES_PASSWORD</span>: <span style="color:#ae81ff">lab</span>
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">POSTGRES_DB</span>: <span style="color:#ae81ff">tienda</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">ports</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#e6db74">&#34;5432:5432&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">volumes</span>:
</span></span><span style="display:flex;"><span>      - <span style="color:#ae81ff">./init.sql:/docker-entrypoint-initdb.d/init.sql:Z</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">command</span>: [<span style="color:#e6db74">&#34;postgres&#34;</span>, <span style="color:#e6db74">&#34;-c&#34;</span>, <span style="color:#e6db74">&#34;log_statement=all&#34;</span>]</span></span></code></pre></div>
</div>
<p>Dos detalles. El <code>:Z</code> del volumen es para que SELinux deje al contenedor leer el fichero; si no usas SELinux, no estorba. Y <code>log_statement=all</code> hace que PostgreSQL escriba en su log <strong>todas</strong> las consultas que recibe. En producción es una barbaridad; aquí es el instrumento de medida de toda la serie.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@milab:~/lab-graphql$ podman compose up -d
</span></span><span style="display:flex;"><span>ignacio@milab:~/lab-graphql$ podman compose logs db | tail -n <span style="color:#ae81ff">3</span>
</span></span><span style="display:flex;"><span>db  | 2026-10-27 18:02:11.431 UTC <span style="color:#f92672">[</span>1<span style="color:#f92672">]</span> LOG:  database system is ready to accept connections</span></span></code></pre></div>
</div>
<p>Si en algún momento quieres empezar de cero, <code>podman compose down -v</code> borra también el volumen de datos y el <code>init.sql</code> se vuelve a ejecutar al arrancar.</p>
<h2 id="el-acceso-a-datos-compartido">El acceso a datos, compartido <a class="ancla" href="#el-acceso-a-datos-compartido" aria-label="Enlace a esta sección">#</a></h2>
<p>Las dos APIs van a usar exactamente el mismo módulo para hablar con la base de datos. Si no, la comparación está trucada.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># db.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> psycopg
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> psycopg.rows <span style="color:#f92672">import</span> dict_row
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>DSN <span style="color:#f92672">=</span> <span style="color:#e6db74">&#34;postgresql://lab:lab@localhost:5432/tienda&#34;</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">conectar</span>():
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> psycopg<span style="color:#f92672">.</span>connect(DSN, row_factory<span style="color:#f92672">=</span>dict_row)</span></span></code></pre></div>
</div>
<p><code>dict_row</code> hace que cada fila venga como un diccionario con el nombre de las columnas, que es lo que FastAPI y Strawberry quieren recibir.</p>
<p>La estructura del repositorio queda así:</p>
<div class="codeblock"><pre tabindex="0"><code>lab-graphql/
├── compose.yaml
├── init.sql
├── db.py
├── api_rest/
│   └── main.py
└── api_graphql/
    └── main.py</code></pre>
</div>
<p>Un aviso que me costó un rato: la carpeta del servidor GraphQL <strong>no</strong> puede llamarse <code>graphql</code>. Strawberry depende de una librería que se llama exactamente así, y un directorio con ese nombre en el directorio de trabajo la tapa. De ahí el <code>api_graphql</code>.</p>
<p>Dependencias, en un entorno virtual:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@milab:~/lab-graphql$ python3 -m venv .venv <span style="color:#f92672">&amp;&amp;</span> source .venv/bin/activate
</span></span><span style="display:flex;"><span><span style="color:#f92672">(</span>.venv<span style="color:#f92672">)</span> ignacio@milab:~/lab-graphql$ pip install fastapi <span style="color:#e6db74">&#34;uvicorn[standard]&#34;</span> <span style="color:#e6db74">&#34;psycopg[binary]&#34;</span> strawberry-graphql</span></span></code></pre></div>
</div>
<h2 id="la-api-rest">La API REST <a class="ancla" href="#la-api-rest" aria-label="Enlace a esta sección">#</a></h2>
<p>Dos endpoints, los dos de la entrada anterior. FastAPI porque es lo que menos ruido mete.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_rest/main.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> fastapi <span style="color:#f92672">import</span> FastAPI, HTTPException, Query
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> db <span style="color:#f92672">import</span> conectar
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>app <span style="color:#f92672">=</span> FastAPI()
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.get</span>(<span style="color:#e6db74">&#34;/usuarios/</span><span style="color:#e6db74">{id}</span><span style="color:#e6db74">&#34;</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuario</span>(id: int):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        fila <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;SELECT * FROM usuarios WHERE id = </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">&#34;</span>, (id,)
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> fila <span style="color:#f92672">is</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">raise</span> HTTPException(<span style="color:#ae81ff">404</span>, <span style="color:#e6db74">&#34;Usuario no encontrado&#34;</span>)
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> fila
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@app.get</span>(<span style="color:#e6db74">&#34;/usuarios/</span><span style="color:#e6db74">{id}</span><span style="color:#e6db74">/pedidos&#34;</span>)
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">pedidos</span>(id: int, ultimos: int <span style="color:#f92672">=</span> Query(<span style="color:#ae81ff">10</span>, ge<span style="color:#f92672">=</span><span style="color:#ae81ff">1</span>, le<span style="color:#f92672">=</span><span style="color:#ae81ff">100</span>)):
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>            <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            SELECT * FROM pedidos
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            WHERE usuario_id = </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ORDER BY fecha DESC
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            LIMIT </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (id, ultimos),
</span></span><span style="display:flex;"><span>        )<span style="color:#f92672">.</span>fetchall()</span></span></code></pre></div>
</div>
<p><code>/usuarios/42</code> devuelve el usuario entero, con sus seis campos, porque así es como se diseñan los endpoints REST: el servidor decide la forma. <code>/usuarios/42/pedidos?ultimos=3</code> devuelve los pedidos enteros, cuatro campos cada uno.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#f92672">(</span>.venv<span style="color:#f92672">)</span> ignacio@milab:~/lab-graphql$ uvicorn api_rest.main:app --port <span style="color:#ae81ff">8000</span></span></span></code></pre></div>
</div>
<h2 id="la-api-graphql">La API GraphQL <a class="ancla" href="#la-api-graphql" aria-label="Enlace a esta sección">#</a></h2>
<p>Strawberry define el esquema con clases de Python y anotaciones de tipo. Compáralo con el SDL de la entrada anterior: es lo mismo, escrito en otro sitio.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-python" data-lang="python"><span style="display:flex;"><span><span style="color:#75715e"># api_graphql/main.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> datetime
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> decimal
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> strawberry
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> fastapi <span style="color:#f92672">import</span> FastAPI
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> strawberry.fastapi <span style="color:#f92672">import</span> GraphQLRouter
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> db <span style="color:#f92672">import</span> conectar
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@strawberry.type</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">Pedido</span>:
</span></span><span style="display:flex;"><span>    id: int
</span></span><span style="display:flex;"><span>    fecha: datetime<span style="color:#f92672">.</span>date
</span></span><span style="display:flex;"><span>    total: decimal<span style="color:#f92672">.</span>Decimal
</span></span><span style="display:flex;"><span>    estado: str
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@strawberry.type</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">Usuario</span>:
</span></span><span style="display:flex;"><span>    id: int
</span></span><span style="display:flex;"><span>    nombre: str
</span></span><span style="display:flex;"><span>    email: str
</span></span><span style="display:flex;"><span>    direccion: str <span style="color:#f92672">|</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>    telefono: str <span style="color:#f92672">|</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>    fecha_alta: datetime<span style="color:#f92672">.</span>date
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">@strawberry.field</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">pedidos</span>(self, ultimos: int <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>) <span style="color:#f92672">-&gt;</span> list[Pedido]:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>            filas <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>                <span style="color:#e6db74">&#34;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                SELECT id, fecha, total, estado FROM pedidos
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                WHERE usuario_id = </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                ORDER BY fecha DESC
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                LIMIT </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">                &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>                (self<span style="color:#f92672">.</span>id, ultimos),
</span></span><span style="display:flex;"><span>            )<span style="color:#f92672">.</span>fetchall()
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> [Pedido(<span style="color:#f92672">**</span>f) <span style="color:#66d9ef">for</span> f <span style="color:#f92672">in</span> filas]
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#a6e22e">@strawberry.type</span>
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">class</span> <span style="color:#a6e22e">Query</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#a6e22e">@strawberry.field</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">def</span> <span style="color:#a6e22e">usuario</span>(self, id: int) <span style="color:#f92672">-&gt;</span> Usuario <span style="color:#f92672">|</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">with</span> conectar() <span style="color:#66d9ef">as</span> con:
</span></span><span style="display:flex;"><span>            fila <span style="color:#f92672">=</span> con<span style="color:#f92672">.</span>execute(
</span></span><span style="display:flex;"><span>                <span style="color:#e6db74">&#34;SELECT * FROM usuarios WHERE id = </span><span style="color:#e6db74">%s</span><span style="color:#e6db74">&#34;</span>, (id,)
</span></span><span style="display:flex;"><span>            )<span style="color:#f92672">.</span>fetchone()
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span> Usuario(<span style="color:#f92672">**</span>fila) <span style="color:#66d9ef">if</span> fila <span style="color:#66d9ef">else</span> <span style="color:#66d9ef">None</span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>schema <span style="color:#f92672">=</span> strawberry<span style="color:#f92672">.</span>Schema(query<span style="color:#f92672">=</span>Query)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>app <span style="color:#f92672">=</span> FastAPI()
</span></span><span style="display:flex;"><span>app<span style="color:#f92672">.</span>include_router(GraphQLRouter(schema), prefix<span style="color:#f92672">=</span><span style="color:#e6db74">&#34;/graphql&#34;</span>)</span></span></code></pre></div>
</div>
<p>Fíjate en dónde está cada consulta SQL. <code>Query.usuario</code> es un resolver: va a por el usuario. <code>Usuario.pedidos</code> es <strong>otro</strong> resolver, que se ejecuta solo si el cliente pide el campo <code>pedidos</code>, y que va a por los pedidos de ese usuario concreto (<code>self.id</code>). Los campos simples (<code>nombre</code>, <code>email</code>…) no tienen resolver: Strawberry los lee directamente del objeto.</p>
<p>Esto es exactamente la estructura que en la entrada anterior llamé &ldquo;un controlador por campo&rdquo;. Guárdate la imagen para la siguiente entrada.</p>
<p>Dos cosas de Strawberry que conviene saber: convierte los nombres a <em>camelCase</em> en el esquema, así que <code>fecha_alta</code> se pide como <code>fechaAlta</code>; y los tipos <code>date</code> y <code>Decimal</code> de Python los expone como escalares <code>Date</code> y <code>Decimal</code> sin que haya que hacer nada.</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span><span style="color:#f92672">(</span>.venv<span style="color:#f92672">)</span> ignacio@milab:~/lab-graphql$ uvicorn api_graphql.main:app --port <span style="color:#ae81ff">8001</span></span></span></code></pre></div>
</div>
<p>Con el servidor levantado, <code>http://localhost:8001/graphql</code> en el navegador abre GraphiQL, una consola para escribir consultas con autocompletado contra el esquema. Es lo que en REST sería el Swagger UI de FastAPI (<code>http://localhost:8000/docs</code>), con la diferencia de que aquí el autocompletado sale del esquema real, no de una descripción paralela.</p>
<h2 id="primera-pantalla-la-ficha-de-un-usuario">Primera pantalla: la ficha de un usuario <a class="ancla" href="#primera-pantalla-la-ficha-de-un-usuario" aria-label="Enlace a esta sección">#</a></h2>
<p>El caso de uso: una pantalla que muestra el nombre de un usuario y la fecha e importe de sus tres últimos pedidos. Nada más.</p>
<h3 id="en-rest">En REST <a class="ancla" href="#en-rest" aria-label="Enlace a esta sección">#</a></h3>
<p>Dos peticiones, porque son dos recursos:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@milab:~$ curl -s localhost:8000/usuarios/42 | jq
</span></span><span style="display:flex;"><span><span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;id&#34;</span>: 42,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;nombre&#34;</span>: <span style="color:#e6db74">&#34;Usuario 42&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;email&#34;</span>: <span style="color:#e6db74">&#34;usuario42@example.org&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;direccion&#34;</span>: <span style="color:#e6db74">&#34;Calle Mayor, 42&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;telefono&#34;</span>: <span style="color:#e6db74">&#34;600000042&#34;</span>,
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;fecha_alta&#34;</span>: <span style="color:#e6db74">&#34;2024-05-06&#34;</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">}</span>
</span></span><span style="display:flex;"><span>ignacio@milab:~$ curl -s <span style="color:#e6db74">&#39;localhost:8000/usuarios/42/pedidos?ultimos=3&#39;</span> | jq
</span></span><span style="display:flex;"><span><span style="color:#f92672">[</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;id&#34;</span>: 317,
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;usuario_id&#34;</span>: 42,
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2026-07-14&#34;</span>,
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;total&#34;</span>: 118.4,
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;estado&#34;</span>: <span style="color:#e6db74">&#34;entregado&#34;</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">}</span>,
</span></span><span style="display:flex;"><span>  ...
</span></span><span style="display:flex;"><span><span style="color:#f92672">]</span></span></span></code></pre></div>
</div>
<p>De los seis campos del usuario, la pantalla usa uno. De los cinco de cada pedido, dos. Y el <code>usuario_id</code> de cada pedido es información que el cliente ya tenía: lo puso él en la URL.</p>
<h3 id="en-graphql">En GraphQL <a class="ancla" href="#en-graphql" aria-label="Enlace a esta sección">#</a></h3>
<p>Una petición, y el cliente escribe la forma de la respuesta:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@milab:~$ curl -s localhost:8001/graphql <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>  -H <span style="color:#e6db74">&#39;Content-Type: application/json&#39;</span> <span style="color:#ae81ff">\
</span></span></span><span style="display:flex;"><span>  -d <span style="color:#e6db74">&#39;{&#34;query&#34;: &#34;{ usuario(id: 42) { nombre pedidos(ultimos: 3) { fecha total } } }&#34;}&#39;</span> | jq
</span></span><span style="display:flex;"><span><span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>  <span style="color:#e6db74">&#34;data&#34;</span>: <span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;usuario&#34;</span>: <span style="color:#f92672">{</span>
</span></span><span style="display:flex;"><span>      <span style="color:#e6db74">&#34;nombre&#34;</span>: <span style="color:#e6db74">&#34;Usuario 42&#34;</span>,
</span></span><span style="display:flex;"><span>      <span style="color:#e6db74">&#34;pedidos&#34;</span>: <span style="color:#f92672">[</span>
</span></span><span style="display:flex;"><span>        <span style="color:#f92672">{</span> <span style="color:#e6db74">&#34;fecha&#34;</span>: <span style="color:#e6db74">&#34;2026-07-14&#34;</span>, <span style="color:#e6db74">&#34;total&#34;</span>: <span style="color:#e6db74">&#34;118.40&#34;</span> <span style="color:#f92672">}</span>,
</span></span><span style="display:flex;"><span>        ...
</span></span><span style="display:flex;"><span>      <span style="color:#f92672">]</span>
</span></span><span style="display:flex;"><span>    <span style="color:#f92672">}</span>
</span></span><span style="display:flex;"><span>  <span style="color:#f92672">}</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">}</span></span></span></code></pre></div>
</div>
<p>Ni un campo de más. Si mañana la pantalla necesita también el <code>estado</code>, el cliente lo añade a la consulta y ya está; nadie toca el servidor.</p>
<p>Si quieres medir el tamaño, es un <code>wc -c</code> al final de cada <code>curl</code>. Los números exactos dependen de los datos que haya generado el <code>random()</code>, pero la proporción es la que esperas: la respuesta GraphQL ocupa bastante menos de la mitad que las dos respuestas REST juntas.</p>
<h2 id="lo-que-ve-postgresql">Lo que ve PostgreSQL <a class="ancla" href="#lo-que-ve-postgresql" aria-label="Enlace a esta sección">#</a></h2>
<p>Aquí es donde el <code>log_statement=all</code> empieza a pagar el alquiler. Deja el log abierto en otra terminal:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>ignacio@milab:~/lab-graphql$ podman compose logs -f db</span></span></code></pre></div>
</div>
<p>Lanza las dos peticiones REST:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>LOG:  statement: SELECT * FROM usuarios WHERE id <span style="color:#f92672">=</span> <span style="color:#ae81ff">42</span>
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT * FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">42</span> ORDER BY fecha DESC LIMIT <span style="color:#ae81ff">3</span></span></span></code></pre></div>
</div>
<p>Y ahora la de GraphQL:</p>
<div class="codeblock"><div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>LOG:  statement: SELECT * FROM usuarios WHERE id <span style="color:#f92672">=</span> <span style="color:#ae81ff">42</span>
</span></span><span style="display:flex;"><span>LOG:  statement: SELECT id, fecha, total, estado FROM pedidos WHERE usuario_id <span style="color:#f92672">=</span> <span style="color:#ae81ff">42</span> ORDER BY fecha DESC LIMIT <span style="color:#ae81ff">3</span></span></span></code></pre></div>
</div>
<p>Dos consultas en los dos casos. Para esta pantalla, lo único que cambia entre REST y GraphQL es la capa HTTP: una petición en vez de dos, y una respuesta a medida en vez de dos respuestas genéricas. La base de datos trabaja lo mismo.</p>
<p>(Si en el log ves <code>execute &lt;unnamed&gt;</code> en lugar de <code>statement</code>, es porque psycopg puede usar sentencias preparadas del lado del servidor; da igual para lo que estamos midiendo.)</p>
<h2 id="dónde-estamos">Dónde estamos <a class="ancla" href="#d%c3%b3nde-estamos" aria-label="Enlace a esta sección">#</a></h2>
<p>Hasta aquí GraphQL parece ganar sin despeinarse: menos peticiones, menos bytes, el cliente manda. Y para esta pantalla es verdad.</p>
<p>El problema es que la pantalla era de un usuario. En la <a href="/posts/2026/graphql-n-mas-1-dataloader-cache/">tercera entrada</a> pido cien usuarios con sus pedidos, con el mismo log abierto, y el resultado es bastante menos elegante.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_d7c5d2b15b24bf51.png"/></item></channel></rss>