<?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>Python – El blog de Ignacio</title><link>https://www.igalvan.es/tags/python/</link><description>Entradas de Python en El blog de Ignacio</description><generator>Hugo -- gohugo.io</generator><language>es</language><copyright>Ignacio Galván Vitas</copyright><lastBuildDate>Wed, 18 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://www.igalvan.es/tags/python/index.xml" rel="self" type="application/rss+xml"/><icon>https://www.igalvan.es/logo.svg</icon><item><title>MCP desde cero: qué es y qué problema resuelve</title><link>https://www.igalvan.es/posts/2026/mcp-desde-cero-que-es/</link><pubDate>Wed, 18 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/mcp-desde-cero-que-es/</guid><description><![CDATA[<p>MCP es una sigla que veía pasar por todas partes sin saber bien qué había detrás. No había trabajado nunca con ello. Esta serie es lo que habría querido encontrar el primer día: empezar de cero, entender qué es, mirar el protocolo por dentro, montar un servidor de verdad sobre PostgreSQL, y después probarlo, romperle el diseño, atacarlo y publicarlo por HTTP.</p>
<p>Son siete entradas. Esta es la primera y es solo teoría, más un servidor de ocho líneas para que haya algo que ejecutar.</p>
<p>Una advertencia que me habría ahorrado una tarde: <strong>MCP ha cambiado mucho este año</strong>. La mayoría de tutoriales que encuentras en internet describen la versión anterior del protocolo (con un «apretón de manos» inicial y sesiones) y una API de Python que ya no existe con ese nombre. Esta serie usa la versión de protocolo <code>2026-07-28</code> y el SDK oficial de Python 2.3, que es lo vigente mientras escribo esto. Cuando algo difiera de lo que verás en otros sitios, lo digo.</p>
<p>El código está en Codeberg: <a href="https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-mcp" target="_blank" rel="noopener">https://codeberg.org/igalvan/blog-public-code/src/branch/main/lab-mcp</a>.</p>
<h2 id="el-problema-que-resuelve">El problema que resuelve <a class="ancla" href="#el-problema-que-resuelve" aria-label="Enlace a esta sección">#</a></h2>
<p>Un asistente de IA, por sí solo, solo sabe lo que sabe. No ve tu base de datos, ni tus ficheros, ni tu sistema de tickets. Para que pueda mirarlos (o hacer algo en ellos) alguien tiene que escribir la integración.</p>
<p>Sin un estándar, cada aplicación con un modelo necesita una integración propia con cada sistema: si hay M aplicaciones y N sistemas, son M × N trabajos. Si te dedicas a bases de datos esto te suena: es el problema que resolvieron ODBC y JDBC. Cada aplicación habla un protocolo común con un <em>driver</em>, y cada base de datos tiene su driver. Pasas de M × N a M + N.</p>
<p>MCP (<em>Model Context Protocol</em>) es eso mismo para asistentes de IA. Lo creó Anthropic y hoy se desarrolla como un proyecto abierto, con <a href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture" target="_blank" rel="noopener">especificación pública</a>, SDK en varios lenguajes y un proceso de propuestas de cambio. Si has usado un editor con autocompletado, la otra comparación útil es con el <em>Language Server Protocol</em>: mismo planteamiento (un protocolo estándar entre el editor y los servidores de cada lenguaje) y, de hecho, también va sobre JSON-RPC.</p>
<h2 id="los-tres-actores">Los tres actores <a class="ancla" href="#los-tres-actores" aria-label="Enlace a esta sección">#</a></h2>
<p>Hay tres piezas, y conviene no mezclar los nombres:</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> host (la aplicación con el modelo)
</span></span><span style="display:flex;"><span> ├── cliente MCP 1 ── stdio ──▶ servidor A   (un proceso en tu máquina)
</span></span><span style="display:flex;"><span> ├── cliente MCP 2 ── stdio ──▶ servidor B   (otro proceso en tu máquina)
</span></span><span style="display:flex;"><span> └── cliente MCP 3 ── HTTP  ──▶ servidor C   (remoto)</span></span></code></pre></div>
</div>
<ul>
<li><strong>Host</strong>: la aplicación donde vive el modelo. Un editor, un asistente de escritorio, una herramienta de línea de comandos, o un programa tuyo.</li>
<li><strong>Cliente MCP</strong>: la parte del host que habla el protocolo. El host crea <strong>uno por cada servidor</strong> al que se conecta; cada cliente mantiene su conexión con su servidor.</li>
<li><strong>Servidor MCP</strong>: un programa que ofrece capacidades. Eso es lo que vamos a escribir.</li>
</ul>
<p>«Servidor» aquí no quiere decir «máquina remota»: un servidor MCP puede ser un proceso que el host lanza en tu propio equipo. Que sea local o remoto depende solo del transporte, que veremos en un momento.</p>
<h2 id="qué-ofrece-un-servidor-tres-cosas">Qué ofrece un servidor: tres cosas <a class="ancla" href="#qu%c3%a9-ofrece-un-servidor-tres-cosas" aria-label="Enlace a esta sección">#</a></h2>
<p>Un servidor puede ofrecer tres tipos de cosas. La diferencia entre ellas no es técnica sino de <strong>quién decide usarlas</strong>, y es la mejor forma de recordarlas:</p>
<table>
  <thead>
      <tr>
          <th>Qué</th>
          <th>Para qué sirve</th>
          <th>Quién decide usarlo</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td><strong>Tool</strong> (herramienta)</td>
          <td>Una función que el modelo puede llamar: buscar usuarios, crear un evento, consultar un pedido.</td>
          <td>El <strong>modelo</strong></td>
      </tr>
      <tr>
          <td><strong>Resource</strong> (recurso)</td>
          <td>Datos de solo lectura con una dirección (URI): un fichero, el esquema de una base de datos, una ficha.</td>
          <td>La <strong>aplicación</strong></td>
      </tr>
      <tr>
          <td><strong>Prompt</strong></td>
          <td>Una plantilla de instrucciones con parámetros, para tareas que se repiten.</td>
          <td>El <strong>usuario</strong></td>
      </tr>
  </tbody>
</table>
<p>Para traducirlo a vocabulario de APIs (a medias, como todas las traducciones): una herramienta se parece a un endpoint RPC con parámetros tipados y un resultado; un recurso, a un <code>GET</code> sobre una URI; y un prompt, a una macro. En la práctica las herramientas son lo que más se usa, y lo que ocupa casi toda la serie.</p>
<p>Lo que hace especial a una herramienta, frente a un endpoint, es <strong>quién la llama y cómo se entera de que existe</strong>. A un endpoint lo llama un programa que escribió una persona leyendo la documentación. A una herramienta MCP la llama un modelo, que se entera de que existe porque el servidor se lo cuenta en tiempo de ejecución: el nombre, una descripción en lenguaje natural y un esquema JSON de los parámetros. El modelo decide si le sirve y con qué argumentos. Esa descripción forma parte de la interfaz, y de ahí sale casi todo lo interesante de las entradas 5 y 6.</p>
<h2 id="cómo-viaja-por-debajo">Cómo viaja por debajo <a class="ancla" href="#c%c3%b3mo-viaja-por-debajo" aria-label="Enlace a esta sección">#</a></h2>
<p>El mensaje es siempre <a href="https://www.jsonrpc.org/" target="_blank" rel="noopener">JSON-RPC 2.0</a>: peticiones con un <code>method</code> y unos <code>params</code>, y respuestas con un <code>result</code> o un <code>error</code>. Hay dos transportes:</p>
<ul>
<li><strong>stdio</strong>: el host lanza el servidor como proceso hijo y le habla por la entrada y la salida estándar. Es lo normal para servidores locales, sin red y sin puertos.</li>
<li><strong>Streamable HTTP</strong>: peticiones <code>POST</code> a una URL (por convención, <code>/mcp</code>). Es lo que se usa para servidores remotos, con autenticación HTTP normal.</li>
</ul>
<p>Y, desde la versión de protocolo <code>2026-07-28</code>, <strong>MCP no tiene estado</strong>. Cada petición lleva dentro todo lo necesario para procesarla: la versión del protocolo y las capacidades del cliente, en un campo <code>_meta</code>. No hay un <code>initialize</code> inicial ni una sesión. Un cliente puede preguntar qué ofrece el servidor con una petición <code>server/discover</code>, pero es opcional.</p>
<p>Que no haya sesión tiene una consecuencia práctica que se aprecia en la última entrada: un servidor remoto se puede repartir entre varias réplicas con un balanceador cualquiera, sin pegajosidad. Con la versión anterior, un cliente abría una sesión y todas sus peticiones tenían que llegar al mismo sitio.</p>
<p>El SDK actual atiende los dos mundos: un cliente moderno usa el protocolo nuevo, y uno antiguo hace su <code>initialize</code> de siempre y también funciona. En la <a href="/posts/2026/mcp-a-mano-json-rpc/">siguiente entrada</a> lo veremos con mensajes escritos a mano.</p>
<h2 id="un-primer-servidor">Un primer servidor <a class="ancla" href="#un-primer-servidor" aria-label="Enlace a esta sección">#</a></h2>
<p>El SDK oficial de Python 2.x se instala con <code>pip</code> (necesita Python 3.10 o posterior):</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>ignacio@localhost:~/lab-mcp$ python3 -m venv .venv &amp;&amp; source .venv/bin/activate
</span></span><span style="display:flex;"><span>ignacio@localhost:~/lab-mcp$ pip install &#34;mcp[cli]&gt;=2,&lt;3&#34;</span></span></code></pre></div>
</div>
<p>Ojo con el <code>&lt;3</code>: lo que instala <code>pip install mcp</code> es la serie 2.x, y conviene fijar el límite superior para que una versión mayor no te rompa los ejemplos.</p>
<p>El servidor mínimo, con una sola herramienta:</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"># hola/hola.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> mcp.server <span style="color:#f92672">import</span> MCPServer
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>mcp <span style="color:#f92672">=</span> MCPServer(<span style="color:#e6db74">&#34;Hola&#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">@mcp.tool</span>()
</span></span><span style="display:flex;"><span><span style="color:#66d9ef">def</span> <span style="color:#a6e22e">sumar</span>(a: int, b: int) <span style="color:#f92672">-&gt;</span> int:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;Suma dos números enteros.&#34;&#34;&#34;</span>
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">return</span> a <span style="color:#f92672">+</span> b
</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">if</span> __name__ <span style="color:#f92672">==</span> <span style="color:#e6db74">&#34;__main__&#34;</span>:
</span></span><span style="display:flex;"><span>    mcp<span style="color:#f92672">.</span>run()</span></span></code></pre></div>
</div>
<p>Tres cosas, que se repetirán toda la serie:</p>
<ul>
<li><code>MCPServer(&quot;Hola&quot;)</code> crea el servidor. Ese nombre es el que verán los clientes. (Si has visto tutoriales con <code>FastMCP</code>, es el mismo concepto con otro nombre: en el SDK 2.x <code>FastMCP</code> ya no existe y se usa <code>MCPServer</code>.)</li>
<li><code>@mcp.tool()</code> convierte la función en herramienta. El <strong>nombre</strong> sale del nombre de la función, la <strong>descripción</strong> de la docstring y el <strong>esquema de los parámetros</strong> de las anotaciones de tipo. No hay que escribir ningún JSON Schema.</li>
<li><code>mcp.run()</code> arranca el servidor; por defecto, por stdio.</li>
</ul>
<p>Si lo ejecutas directamente se queda esperando mensajes por la entrada estándar, que no es muy interesante. Para hablar con él hace falta un cliente, y el SDK trae uno. Este lanza <code>hola.py</code> como proceso hijo, pregunta qué herramientas ofrece y llama a una:</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"># hola/cliente_hola.py</span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> sys
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">import</span> anyio
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span><span style="color:#f92672">from</span> mcp <span style="color:#f92672">import</span> Client, StdioServerParameters
</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">main</span>() <span style="color:#f92672">-&gt;</span> <span style="color:#66d9ef">None</span>:
</span></span><span style="display:flex;"><span>    <span style="color:#75715e"># Lanza hola.py como proceso hijo y habla con él por stdin/stdout.</span>
</span></span><span style="display:flex;"><span>    params <span style="color:#f92672">=</span> StdioServerParameters(command<span style="color:#f92672">=</span>sys<span style="color:#f92672">.</span>executable, args<span style="color:#f92672">=</span>[<span style="color:#e6db74">&#34;hola.py&#34;</span>])
</span></span><span style="display:flex;"><span>    <span style="color:#66d9ef">async</span> <span style="color:#66d9ef">with</span> Client(params) <span style="color:#66d9ef">as</span> client:
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">&#34;servidor:&#34;</span>, client<span style="color:#f92672">.</span>server_info<span style="color:#f92672">.</span>name, <span style="color:#e6db74">&#34;| protocolo:&#34;</span>, client<span style="color:#f92672">.</span>protocol_version)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">for</span> herramienta <span style="color:#f92672">in</span> (<span style="color:#66d9ef">await</span> client<span style="color:#f92672">.</span>list_tools())<span style="color:#f92672">.</span>tools:
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">&#34;herramienta:&#34;</span>, herramienta<span style="color:#f92672">.</span>name, <span style="color:#e6db74">&#34;-&#34;</span>, herramienta<span style="color:#f92672">.</span>description)
</span></span><span style="display:flex;"><span>            print(<span style="color:#e6db74">&#34;  parámetros:&#34;</span>, herramienta<span style="color:#f92672">.</span>input_schema[<span style="color:#e6db74">&#34;properties&#34;</span>])
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>        resultado <span style="color:#f92672">=</span> <span style="color:#66d9ef">await</span> client<span style="color:#f92672">.</span>call_tool(<span style="color:#e6db74">&#34;sumar&#34;</span>, {<span style="color:#e6db74">&#34;a&#34;</span>: <span style="color:#ae81ff">2</span>, <span style="color:#e6db74">&#34;b&#34;</span>: <span style="color:#ae81ff">3</span>})
</span></span><span style="display:flex;"><span>        print(<span style="color:#e6db74">&#34;resultado:&#34;</span>, resultado<span style="color:#f92672">.</span>structured_content)
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>
</span></span><span style="display:flex;"><span>anyio<span style="color:#f92672">.</span>run(main)</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>ignacio@localhost:~/lab-mcp$ cd hola &amp;&amp; python cliente_hola.py
</span></span><span style="display:flex;"><span>servidor: Hola | protocolo: 2026-07-28
</span></span><span style="display:flex;"><span>herramienta: sumar - Suma dos números enteros.
</span></span><span style="display:flex;"><span>  parámetros: {&#39;a&#39;: {&#39;title&#39;: &#39;A&#39;, &#39;type&#39;: &#39;integer&#39;}, &#39;b&#39;: {&#39;title&#39;: &#39;B&#39;, &#39;type&#39;: &#39;integer&#39;}}
</span></span><span style="display:flex;"><span>resultado: {&#39;result&#39;: 5}</span></span></code></pre></div>
</div>
<p>El cliente ha descubierto la herramienta sin que se la hayamos descrito en ningún sitio: nombre, descripción y los dos parámetros enteros salieron de la función. Y el resultado vuelve como <code>{'result': 5}</code>: MCP envuelve en un objeto lo que no lo es.</p>
<h2 id="lo-que-mcp-no-es">Lo que MCP no es <a class="ancla" href="#lo-que-mcp-no-es" aria-label="Enlace a esta sección">#</a></h2>
<p>Para no esperar de él lo que no hace:</p>
<ul>
<li><strong>No decide cómo usa el modelo las herramientas.</strong> El protocolo solo define cómo se anuncian y cómo se llaman. Qué herramienta elige el modelo, con qué argumentos y cuándo, es cosa del modelo y del host. El servidor no controla eso.</li>
<li><strong>No es una capa de seguridad.</strong> El protocolo lleva cosas de autorización para servidores remotos, pero que un servidor sea MCP no lo hace seguro ni de fiar. Un servidor local es un proceso normal con tus permisos. De esto va la entrada 6.</li>
<li><strong>No es un framework de agentes.</strong> Un agente puede usar MCP para llegar a sus herramientas, pero MCP no orquesta nada.</li>
</ul>
<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>Tenemos el vocabulario (host, cliente, servidor; herramientas, recursos, prompts), sabemos que va sobre JSON-RPC por stdio o HTTP, que ahora no tiene estado, y que un servidor mínimo son ocho líneas.</p>
<p>En la <a href="/posts/2026/mcp-a-mano-json-rpc/">siguiente entrada</a> quito el SDK de en medio y le hablo a este mismo servidor escribiendo los mensajes a mano, por stdio y por HTTP con <code>curl</code>. Es la forma más rápida de que el protocolo deje de parecer magia.</p>
<p>Para saber más, la <a href="https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture" target="_blank" rel="noopener">descripción de la arquitectura</a> en la documentación oficial y la <a href="https://py.sdk.modelcontextprotocol.io/" target="_blank" rel="noopener">documentación del SDK de Python</a>.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_2701baec85c8552c.png"/></item><item><title>Al menos una vez, y lo que eso te obliga a hacer</title><link>https://www.igalvan.es/posts/2026/colas-al-menos-una-vez-idempotencia/</link><pubDate>Fri, 06 Nov 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/colas-al-menos-una-vez-idempotencia/</guid><description><![CDATA[<p>Tercera y última entrada. En la <a href="/posts/2026/colas-de-mensajes-para-gente-de-sincrono/">primera</a> saqué el correo del endpoint a una cola; en la <a href="/posts/2026/colas-cuando-el-consumidor-se-cae/">segunda</a> rompí el consumidor de cuatro formas y acabé con ack manual, reintentos con espera y una cola de fallidos. El sistema ya no pierde mensajes.</p>
<p>Lo que hace ahora, en cambio, es repetirlos. Y eso no es un bug: es la única garantía que una cola puede darte de verdad.</p>
<h2 id="fallo-5-el-correo-se-envía-dos-veces">Fallo 5: el correo se envía dos veces <a class="ancla" href="#fallo-5-el-correo-se-env%c3%ada-dos-veces" aria-label="Enlace a esta sección">#</a></h2>
<p>Vuelve al worker de la segunda entrada y fíjate en el orden de las cosas dentro de <code>procesar</code>: primero <code>enviar_correo</code>, después <code>basic_ack</code>. Entre una y otra hay un hueco. Lo voy a hacer más ancho para poder meter el dedo:</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 solo para el experimento)</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">, redelivered=</span><span style="color:#e6db74">{</span>metodo<span style="color:#f92672">.</span>redelivered<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:#f92672">...</span>
</span></span><span style="display:flex;"><span>        <span style="color:#66d9ef">return</span>
</span></span><span style="display:flex;"><span>    time<span style="color:#f92672">.</span>sleep(<span style="color:#ae81ff">3</span>)  <span style="color:#75715e"># el hueco entre hacer el trabajo y confirmarlo</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>Lanza un pedido, espera a ver la línea de <code>[correo] ... enviada</code>, y en los tres segundos siguientes, <code>pkill -9</code>:</p>
<div class="codeblock"><pre tabindex="0"><code>ignacio@zeus:~/lab-colas$ python worker.py
[worker] esperando mensajes
[worker] pedido 520, intento 1, redelivered=False
[correo] confirmación del pedido 520 enviada
Killed</code></pre>
</div>
<p>El correo ha salido. El ack no. RabbitMQ ve caer la conexión y devuelve el mensaje a la cola, como debe. Arranca el worker:</p>
<div class="codeblock"><pre tabindex="0"><code>[worker] pedido 520, intento 1, redelivered=True
[correo] confirmación del pedido 520 enviada</code></pre>
</div>
<p>Dos correos de confirmación del mismo pedido. El usuario tiene dos mensajes en su bandeja y, si en vez de un correo fuera un cargo en la tarjeta, dos cargos.</p>
<p>Y aquí va la frase que cuesta aceptar viniendo del mundo síncrono: <strong>esto no tiene arreglo en la cola.</strong> Si haces ack antes de enviar, el fallo 1 de la entrada anterior vuelve (el worker muere después del ack y antes del envío: correo perdido). Si haces ack después, el worker puede morir entre el envío y el ack: correo duplicado. No hay un tercer sitio donde poner el ack. Puedes elegir entre <em>como mucho una vez</em> (ack antes) y <em>al menos una vez</em> (ack después), y para un correo de confirmación, o un cargo, o cualquier cosa que no quieras perder, eliges al menos una vez y asumes el duplicado.</p>
<p>Hay brókers que anuncian &ldquo;exactamente una vez&rdquo;. Lo que dan, cuando lo dan, es exactamente una vez <em>dentro del bróker</em>; en cuanto el consumidor hace algo fuera (un correo, una llamada HTTP, un <code>INSERT</code> en otra base de datos), vuelves a tener el hueco.</p>
<h2 id="arreglo-5-que-repetir-no-haga-daño">Arreglo 5: que repetir no haga daño <a class="ancla" href="#arreglo-5-que-repetir-no-haga-da%c3%b1o" aria-label="Enlace a esta sección">#</a></h2>
<p>Si no puedes evitar que un mensaje llegue dos veces, haz que la segunda vez no haga nada. Eso es idempotencia, y se consigue apuntando lo que ya has hecho en un sitio que sobreviva a la muerte del worker. Tengo un PostgreSQL al lado; sirve.</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">-- añadido a init.sql
</span></span></span><span style="display:flex;"><span><span style="color:#66d9ef">CREATE</span> <span style="color:#66d9ef">TABLE</span> correos_enviados (
</span></span><span style="display:flex;"><span>  pedido_id  int <span style="color:#66d9ef">PRIMARY</span> <span style="color:#66d9ef">KEY</span> <span style="color:#66d9ef">REFERENCES</span> pedidos(id),
</span></span><span style="display:flex;"><span>  enviado_en timestamptz <span style="color:#66d9ef">NOT</span> <span style="color:#66d9ef">NULL</span> <span style="color:#66d9ef">DEFAULT</span> now()
</span></span><span style="display:flex;"><span>);</span></span></code></pre></div>
</div>
<p>Y el worker, antes de enviar, intenta reservar el pedido:</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">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:#66d9ef">def</span> <span style="color:#a6e22e">reservar</span>(pedido_id: int) <span style="color:#f92672">-&gt;</span> bool:
</span></span><span style="display:flex;"><span>    <span style="color:#e6db74">&#34;&#34;&#34;True si somos los primeros en ocuparnos de este pedido.&#34;&#34;&#34;</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;&#34;&#34;
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            INSERT INTO correos_enviados (pedido_id) VALUES (</span><span style="color:#e6db74">%s</span><span style="color:#e6db74">)
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            ON CONFLICT (pedido_id) DO NOTHING
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            RETURNING pedido_id
</span></span></span><span style="display:flex;"><span><span style="color:#e6db74">            &#34;&#34;&#34;</span>,
</span></span><span style="display:flex;"><span>            (pedido_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> fila <span style="color:#f92672">is</span> <span style="color:#f92672">not</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><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">, redelivered=</span><span style="color:#e6db74">{</span>metodo<span style="color:#f92672">.</span>redelivered<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></span><span style="display:flex;"><span>    <span style="color:#66d9ef">if</span> <span style="color:#f92672">not</span> reservar(pedido[<span style="color:#e6db74">&#34;id&#34;</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"> ya tratado, ignoro&#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_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">return</span>
</span></span><span style="display:flex;"><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:#f92672">...</span>  <span style="color:#75715e"># igual que en la segunda entrada</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>El <code>INSERT ... ON CONFLICT DO NOTHING RETURNING</code> es el truco: si la fila no existía, la inserta y devuelve el id; si existía, no hace nada y no devuelve nada. Atómico, en una sola sentencia, sin ventana para que dos workers se cuelen. Repite el experimento del <code>pkill -9</code> tras el envío:</p>
<div class="codeblock"><pre tabindex="0"><code>[worker] pedido 521, intento 1, redelivered=True
[worker] pedido 521 ya tratado, ignoro</code></pre>
</div>
<p>Un correo. La reentrega llega, la reserva falla porque ya está hecha, y el worker se limita a confirmar el mensaje para que RabbitMQ lo olvide.</p>
<h3 id="el-hueco-se-ha-movido-no-ha-desaparecido">El hueco se ha movido, no ha desaparecido <a class="ancla" href="#el-hueco-se-ha-movido-no-ha-desaparecido" aria-label="Enlace a esta sección">#</a></h3>
<p>Sé honesto con esto o el lector lo descubrirá solo. Ahora el orden es: reservar, enviar, ack. Si el worker muere <strong>entre reservar y enviar</strong>, el pedido queda marcado como tratado y el correo no sale nunca. He cambiado un duplicado por una pérdida, en una ventana mucho más pequeña (unos milisegundos frente a los dos segundos del envío) y, sobre todo, <strong>detectable</strong>: la fila en <code>correos_enviados</code> existe, y el correo no. Un trabajo de limpieza que compare esa tabla con el registro del servidor de correo, o una columna <code>estado</code> (<code>reservado</code> → <code>enviado</code>) con un reintento para los que llevan demasiado tiempo en <code>reservado</code>, lo cierra del todo. Lo dejo fuera porque ya no es sobre colas, pero que conste que el circuito completo tiene una pieza más.</p>
<p>La regla general, que vale para cualquier cosa que haga efectos fuera de la base de datos: <strong>o la operación es naturalmente idempotente</strong> (poner <code>estado = 'enviado'</code> lo es; <code>saldo = saldo - 10</code> no), <strong>o le pones una clave que lo haga idempotente</strong> (el id del pedido, un UUID generado por el productor y viajando en el mensaje). Si no hay ninguna de las dos, el duplicado acabará ocurriendo.</p>
<h2 id="lo-mismo-del-lado-del-productor">Lo mismo, del lado del productor <a class="ancla" href="#lo-mismo-del-lado-del-productor" aria-label="Enlace a esta sección">#</a></h2>
<p>He hablado todo el rato del consumidor, pero el endpoint de la primera entrada tiene exactamente el mismo problema al revé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-python" data-lang="python"><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 style="color:#e6db74">&#34;INSERT INTO pedidos ... RETURNING ...&#34;</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>
<p>Si <code>publicar</code> falla (RabbitMQ caído, un corte de red), el pedido está en la base de datos y el mensaje no existe: un pedido sin correo. Si inviertes el orden y publicas antes de insertar, puedes tener un correo de un pedido que nunca se guardó. Es el mismo hueco de siempre, entre dos sistemas que no comparten transacción.</p>
<p>La solución tiene nombre, <em>transactional outbox</em>, y es más sencilla de lo que suena: en la misma transacción que inserta el pedido, insertas también una fila en una tabla <code>mensajes_pendientes</code>. Las dos filas se guardan o ninguna. Y un proceso aparte lee esa tabla, publica en RabbitMQ y borra la fila al conseguirlo. Ese proceso vuelve a ser un &ldquo;al menos una vez&rdquo; (puede publicar y morir antes de borrar), así que el consumidor tiene que ser idempotente. Que ya lo es. Todo encaja.</p>
<p>No lo implemento aquí porque son treinta líneas más y la entrada ya va larga, pero es la pieza que convierte el laboratorio en algo que pondrías en producción.</p>
<h2 id="cuándo-una-cola-es-demasiado">Cuándo una cola es demasiado <a class="ancla" href="#cu%c3%a1ndo-una-cola-es-demasiado" aria-label="Enlace a esta sección">#</a></h2>
<p>Tres entradas después, la pregunta que debería ir antes de instalar RabbitMQ: ¿lo necesito?</p>
<p>Un bróker de mensajes es un sistema más que mantener, monitorizar, actualizar y que puede caerse. Antes de meterlo, dos alternativas que resuelven una parte sorprendente de los casos:</p>
<ul>
<li><strong>Una tarea en segundo plano en el propio servidor web.</strong> FastAPI tiene <code>BackgroundTasks</code>: el endpoint responde y el correo se envía después en el mismo proceso. Resuelve el problema de la latencia (el primero de la serie) y nada más: si el proceso muere, la tarea se pierde, y no hay reintentos ni cola de fallidos. Para cosas que da igual perder, sobra.</li>
<li><strong>Una tabla de tareas en PostgreSQL.</strong> <code>INSERT INTO tareas</code> en la misma transacción que el pedido, y un worker que hace <code>SELECT ... FOR UPDATE SKIP LOCKED</code> para cogerlas de una en una. Tienes persistencia, reintentos (una columna <code>intentos</code>), fallidos (una columna <code>estado</code>), varios workers en paralelo, y la transacción con el pedido gratis, que es justo lo que el outbox intentaba conseguir. Lo que no tienes es un bróker que empuje los mensajes: el worker sondea cada segundo o cada cinco. Para la inmensa mayoría de sistemas que no son de alta frecuencia es más que suficiente, y es una dependencia menos.</li>
</ul>
<p>RabbitMQ (o cualquier bróker) empieza a compensar cuando hay varios productores y consumidores que son sistemas distintos, cuando el volumen hace que sondear una tabla sea un problema, cuando quieres enrutar un mismo mensaje a varios consumidores que no se conocen, o cuando necesitas que el bróker esté entre dos sistemas que no deben compartir una base de datos.</p>
<p>Y aun entonces, la cola es la fontanería. Lo que se ha visto en esta serie (ack, reintentos, fallidos, idempotencia, outbox) no lo resuelve el bróker: lo resuelves tú en el diseño de lo que viaja por la cola y de lo que hace quien lo recibe. Cambiar RabbitMQ por otro producto cambia los nombres de las piezas, no el trabajo.</p>
<h2 id="lo-que-ha-enseñado-la-serie">Lo que ha enseñado la serie <a class="ancla" href="#lo-que-ha-ense%c3%b1ado-la-serie" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li>Una cola desacopla en el tiempo: el productor termina sin esperar al consumidor, y el consumidor puede no existir en ese momento.</li>
<li><code>auto_ack</code> pierde mensajes; el ack manual los conserva, pero convierte las caídas en reentregas.</li>
<li>Reencolar a la misma cola es un bucle; rechazar hacia un DLX con una cola de espera son reintentos con pausa, y una cola de fallidos aparta lo irrecuperable.</li>
<li>Al menos una vez es lo único que hay. Idempotencia en el consumidor, con una clave en una tabla, es el precio.</li>
<li>El productor tiene el hueco simétrico; el outbox lo cierra.</li>
<li>Antes de un bróker, una tabla de tareas en la base de datos que ya tienes resuelve más de lo que parece.</li>
</ul>
<p>El código de las tres entradas 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>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_1ce61963e9c4a93f.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><item><title>Recursos para aprender machine learning en Python (otoño de 2026)</title><link>https://www.igalvan.es/posts/2026/recursos-machine-learning-python/</link><pubDate>Sun, 25 Oct 2026 00:00:00 +0000</pubDate><guid>https://www.igalvan.es/posts/2026/recursos-machine-learning-python/</guid><description><![CDATA[<p>Hace poco monté <a href="/posts/2026/laboratorio-machine-learning-ubuntu/">un pequeño laboratorio para trastear con machine learning en Ubuntu 26.04</a> (solo CPU, <code>venv</code> + <code>pip</code>, scikit-learn, Jupyter y PyTorch). Lo siguiente era decidir <em>con qué</em> aprender. El problema de este campo es que la mitad de los enlaces que circulan por ahí apuntan a cursos de 2019 con TensorFlow 1 y a libros con dos ediciones de retraso. Así que me he puesto a comprobar qué sigue vivo y actualizado a octubre de 2026, y esto es lo que ha quedado.</p>
<p>Criterios: material gratuito o con versión gratuita, en Python, con código que se puede ejecutar hoy sin pelearse con dependencias muertas, y revisado o publicado en los últimos dos años. Si algo tiene truco, lo digo.</p>
<h2 id="primero-las-versiones-que-mandan">Primero, las versiones que mandan <a class="ancla" href="#primero-las-versiones-que-mandan" aria-label="Enlace a esta sección">#</a></h2>
<p>Antes de instalar nada conviene saber dónde está cada cosa:</p>
<ul>
<li><strong>scikit-learn 1.9.0</strong> (junio de 2026). Soporta Python 3.11 a 3.14 e incorpora <code>narwhals</code> como dependencia para hablar con más librerías de dataframes (pandas, Polars&hellip;). Se instala con <code>pip install -U scikit-learn</code>.</li>
<li><strong>PyTorch 2.14.1</strong> (septiembre de 2026), junto con TorchVision 0.29.1. Para CPU basta con <code>pip install torch torchvision</code>, pero mira siempre la orden exacta en la página oficial de instalación porque cambia con cada versión.</li>
</ul>
<p>Esto importa porque muchos tutoriales escritos para PyTorch 1.x o para scikit-learn 0.2x funcionan, pero tienen avisos de deprecación por todas partes. Si ves <code>sklearn.cross_validation</code> en un notebook, cierra la pestaña.</p>
<h2 id="documentación-oficial-sí-de-verdad">Documentación oficial (sí, de verdad) <a class="ancla" href="#documentaci%c3%b3n-oficial-s%c3%ad-de-verdad" aria-label="Enlace a esta sección">#</a></h2>
<ul>
<li><strong>Guía de usuario de scikit-learn</strong> — <a href="https://scikit-learn.org/stable/user_guide.html" target="_blank" rel="noopener">https://scikit-learn.org/stable/user_guide.html</a>. No es solo referencia de API: la guía de usuario explica cada familia de algoritmos con ejemplos ejecutables y es, en la práctica, un manual de machine learning clásico. Los <em>release highlights</em> de cada versión son la mejor forma de ponerse al día si llevas tiempo sin tocarlo.</li>
<li><strong>Tutoriales de PyTorch</strong> — <a href="https://pytorch.org/tutorials/" target="_blank" rel="noopener">https://pytorch.org/tutorials/</a>. El &ldquo;Learn the Basics&rdquo; (tensores, <code>Dataset</code>/<code>DataLoader</code>, autograd, bucle de entrenamiento) se actualiza con cada versión y es lo primero que haría quien ya sabe Python pero nunca ha entrenado una red.</li>
</ul>
<h2 id="machine-learning-clásico-con-scikit-learn">Machine learning clásico con scikit-learn <a class="ancla" href="#machine-learning-cl%c3%a1sico-con-scikit-learn" aria-label="Enlace a esta sección">#</a></h2>
<h3 id="machine-learning-in-python-with-scikit-learn-inria">Machine learning in Python with scikit-learn (Inria) <a class="ancla" href="#machine-learning-in-python-with-scikit-learn-inria" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://inria.github.io/scikit-learn-mooc/" target="_blank" rel="noopener">https://inria.github.io/scikit-learn-mooc/</a></p>
<p>El MOOC que hace el propio Inria, la casa de scikit-learn. Es el curso que recomendaría a cualquiera que quiera entender bien el flujo completo: preprocesado, pipelines, validación cruzada, ajuste de hiperparámetros, modelos lineales, árboles y ensembles, interpretación. Todo con notebooks ejecutables y licencia CC-BY. La versión estática se puede seguir sin matricularse; el curso completo (foro, quizzes) está en la plataforma FUN-MOOC y es gratuito. El repositorio sigue recibiendo commits en 2026, así que el código funciona con versiones actuales.</p>
<p>Si solo vas a hacer un curso de esta lista, que sea este.</p>
<h3 id="machine-learning-for-beginners-microsoft">Machine Learning for Beginners (Microsoft) <a class="ancla" href="#machine-learning-for-beginners-microsoft" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://github.com/microsoft/ML-For-Beginners" target="_blank" rel="noopener">https://github.com/microsoft/ML-For-Beginners</a></p>
<p>Doce semanas de lecciones sobre machine learning clásico con Python y scikit-learn: regresión, clasificación, clustering, procesamiento de lenguaje natural clásico, series temporales. Está en GitHub con licencia MIT, por lo que puedes clonarlo y trabajarlo offline. Más guiado y menos profundo que el de Inria; buena alternativa si prefieres algo con estructura de &ldquo;una lección por día&rdquo;.</p>
<h3 id="kaggle-learn">Kaggle Learn <a class="ancla" href="#kaggle-learn" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://www.kaggle.com/learn" target="_blank" rel="noopener">https://www.kaggle.com/learn</a></p>
<p>Microcursos de tres a cinco horas, gratuitos y con certificado gratuito. <em>Intro to Machine Learning</em> e <em>Intermediate Machine Learning</em> siguen siendo la vía de entrada más rápida: en una tarde tienes un modelo entrenado sobre datos reales. Después, el propio Kaggle te sirve de campo de pruebas con sus datasets y competiciones.</p>
<h3 id="machine-learning-crash-course-google">Machine Learning Crash Course (Google) <a class="ancla" href="#machine-learning-crash-course-google" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://developers.google.com/machine-learning/crash-course" target="_blank" rel="noopener">https://developers.google.com/machine-learning/crash-course</a></p>
<p>Google lo reescribió hace poco y ahora cubre, además de regresión y clasificación, redes neuronales, modelos de lenguaje grandes, sistemas en producción y equidad. Totalmente gratuito, sin certificado. Es más conceptual que práctico (menos código que los anteriores), pero las visualizaciones interactivas son muy buenas para intuir qué hace cada parámetro.</p>
<p>Ojo: <strong>Google AI Essentials, que todo el mundo sigue recomendando como gratuito, ya no lo es</strong>; está detrás de una suscripción tanto en Coursera como en Google Skills. Lo gratuito de Google son el Crash Course y la ruta corta de introducción a la IA generativa.</p>
<h2 id="deep-learning-con-pytorch">Deep learning con PyTorch <a class="ancla" href="#deep-learning-con-pytorch" aria-label="Enlace a esta sección">#</a></h2>
<h3 id="neural-networks-zero-to-hero-andrej-karpathy">Neural Networks: Zero to Hero (Andrej Karpathy) <a class="ancla" href="#neural-networks-zero-to-hero-andrej-karpathy" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://karpathy.ai/zero-to-hero.html" target="_blank" rel="noopener">https://karpathy.ai/zero-to-hero.html</a></p>
<p>Vídeos en YouTube, con repositorios enlazados, donde Karpathy construye desde cero un motor de autograd (micrograd), un modelo de lenguaje de caracteres, un MLP, batchnorm, WaveNet y, al final, GPT. Unas 19 horas. Es el mejor material que conozco para entender <em>qué hace PyTorch por debajo</em> antes de usarlo como caja negra. Pide algo de soltura con Python y no asustarse con derivadas.</p>
<p>En la misma línea, su proyecto <strong>nanochat</strong> (<a href="https://github.com/karpathy/nanochat" target="_blank" rel="noopener">https://github.com/karpathy/nanochat</a>) es un pipeline completo y legible para entrenar un pequeño chatbot tipo ChatGPT: tokenizador, preentrenamiento, fine-tuning e inferencia. Está pensado para GPUs, así que en un portátil con CPU sirve más para leer código que para ejecutarlo, pero como lectura es oro. Y será el proyecto final de <strong>LLM101n</strong>, el curso de su empresa Eureka Labs que aún no se ha publicado.</p>
<h3 id="practical-deep-learning-for-coders-fastai">Practical Deep Learning for Coders (fast.ai) <a class="ancla" href="#practical-deep-learning-for-coders-fastai" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://course.fast.ai/" target="_blank" rel="noopener">https://course.fast.ai/</a></p>
<p>Enfoque <em>top-down</em>: en la primera lección ya entrenas un clasificador de imágenes y la teoría llega después. Gratuito, con un libro de acompañamiento también gratuito en forma de notebooks. Dos matices honestos: la Parte 1 actual es la de 2022 y no ha habido una nueva edición desde entonces (el trabajo reciente de fast.ai es un curso aparte, de pago, con Answer.AI), y la librería <code>fastai</code> añade una capa sobre PyTorch que luego hay que desaprender un poco. Sigue siendo muy bueno; solo que no esperes LLMs al día.</p>
<h3 id="mit-6s191-introduction-to-deep-learning">MIT 6.S191: Introduction to Deep Learning <a class="ancla" href="#mit-6s191-introduction-to-deep-learning" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://introtodeeplearning.com/" target="_blank" rel="noopener">https://introtodeeplearning.com/</a></p>
<p>El curso introductorio del MIT se imparte cada enero y publican vídeos, diapositivas y labs en PyTorch. La edición de 2026 ya está colgada, así que es de lo más actual que hay con sello universitario. Gratuito; el certificado de edX es de pago.</p>
<h3 id="machine-learning-with-python-freecodecamp">Machine Learning with Python (freeCodeCamp) <a class="ancla" href="#machine-learning-with-python-freecodecamp" aria-label="Enlace a esta sección">#</a></h3>
<p><a href="https://www.freecodecamp.org/learn/machine-learning-with-python/" target="_blank" rel="noopener">https://www.freecodecamp.org/learn/machine-learning-with-python/</a></p>
<p>El currículo de freeCodeCamp se ha pasado a PyTorch (antes era TensorFlow) y termina con cinco proyectos obligatorios para obtener un certificado, que es gratuito de verdad. Unas 30 horas. Más orientado a &ldquo;hacer&rdquo; que a &ldquo;entender&rdquo;, pero el formato de proyectos evaluados funciona bien para no dejarlo a medias.</p>
<h2 id="modelos-de-lenguaje-y-agentes-hugging-face">Modelos de lenguaje y agentes (Hugging Face) <a class="ancla" href="#modelos-de-lenguaje-y-agentes-hugging-face" aria-label="Enlace a esta sección">#</a></h2>
<p><a href="https://huggingface.co/learn" target="_blank" rel="noopener">https://huggingface.co/learn</a></p>
<p>Hugging Face se ha convertido, sin hacer ruido, en el mejor catálogo gratuito de cursos sobre la parte moderna del asunto:</p>
<ul>
<li><strong>LLM Course</strong>: doce capítulos con la librería Transformers, desde tokenizadores hasta fine-tuning y despliegue. Hay traducción al español en marcha, hecha por la comunidad, aunque incompleta.</li>
<li><strong>Agents Course</strong>: cinco unidades sobre agentes (smolagents, LlamaIndex, LangGraph) con proyecto final y <strong>certificación gratuita</strong>. Es el curso de agentes más recomendado de 2026 y con razón.</li>
<li><strong>MCP Course</strong> y <strong>smol course</strong>: para quien quiera meterse en el protocolo de contexto de modelos o en el fine-tuning de modelos pequeños.</li>
</ul>
<p>Todo se puede leer sin cuenta; con una cuenta gratuita se hacen los ejercicios y se consigue el certificado. El código está pensado para Colab, pero los notebooks corren igual en un Jupyter local.</p>
<p>Como complemento escrito, <strong>AI Agents for Beginners</strong> de Microsoft (<a href="https://github.com/microsoft/ai-agents-for-beginners" target="_blank" rel="noopener">https://github.com/microsoft/ai-agents-for-beginners</a>) son quince lecciones en GitHub, con licencia MIT, para quien prefiera leer código a ver vídeos.</p>
<h2 id="libros">Libros <a class="ancla" href="#libros" aria-label="Enlace a esta sección">#</a></h2>
<p>Aquí es donde más cuidado hay que tener con las ediciones viejas.</p>
<ul>
<li><strong>Hands-On Machine Learning with Scikit-Learn and PyTorch</strong> — Aurélien Géron (O&rsquo;Reilly, finales de 2025). Es la nueva encarnación del clásico <em>Hands-On Machine Learning</em>, que en sus tres ediciones anteriores usaba Keras y TensorFlow. Esta abandona TensorFlow, pasa a PyTorch, se apoya en el ecosistema de Hugging Face y añade transformers, modelos de difusión y agentes con aprendizaje por refuerzo. Si vas a comprar un solo libro, este. <strong>No compres la tercera edición de 2022 pensando que es la misma</strong>: no lo es.</li>
<li><strong>Machine Learning with PyTorch and Scikit-Learn</strong> — Sebastian Raschka, Yuxi Liu y Vahid Mirjalili (Packt, 2022). Sigue vigente para ML clásico más deep learning básico en PyTorch; el código está mantenido en GitHub. Alternativa sólida al de Géron, algo más académica.</li>
<li><strong>Build a Large Language Model (From Scratch)</strong> — Sebastian Raschka (Manning, 2024) y su continuación <strong>Build a Reasoning Model (From Scratch)</strong> (Manning, agosto de 2026). El primero implementa un GPT en PyTorch puro, línea a línea; el segundo parte de un modelo preentrenado y añade razonamiento con <em>chain-of-thought</em>, autoconsistencia, aprendizaje por refuerzo con recompensas verificables (GRPO) y destilación. Son los libros que leería después de Karpathy.</li>
<li><strong>Speech and Language Processing</strong> — Jurafsky y Martin. El borrador de la tercera edición es gratuito en PDF y se actualiza continuamente; la versión de 2026 ya incluye capítulos sobre instruction tuning, RLHF, RAG, agentes y evaluación. Para la parte de lenguaje, no hay nada comparable que sea gratis.</li>
</ul>
<h2 id="un-itinerario-razonable">Un itinerario razonable <a class="ancla" href="#un-itinerario-razonable" aria-label="Enlace a esta sección">#</a></h2>
<p>Para alguien que ya programa en Python y quiere aprender en serio sin GPU:</p>
<ol>
<li><strong>Kaggle Learn</strong> (Intro + Intermediate): una tarde, para tener algo funcionando y ver de qué va.</li>
<li><strong>MOOC de Inria</strong>: el núcleo del ML clásico con scikit-learn, bien hecho. Unas semanas.</li>
<li><strong>Karpathy, Zero to Hero</strong>: para entender redes neuronales y autograd desde dentro. En CPU va perfectamente hasta el GPT pequeño.</li>
<li><strong>Tutoriales oficiales de PyTorch</strong> + el libro de Géron como referencia.</li>
<li><strong>Hugging Face LLM Course</strong> y, si apetece, el <strong>Agents Course</strong>.</li>
</ol>
<p>Lo que he dejado fuera a propósito: cualquier cosa basada en TensorFlow 1 o Keras 2 (sigue habiendo cursos de Coursera así), los <em>bootcamps</em> de pago que reempaquetan lo anterior, y las listas de &ldquo;100 recursos&rdquo; que nadie ha comprobado. Si algún enlace de arriba deja de funcionar o se queda viejo, agradezco el aviso.</p>
]]></description><media:thumbnail url="https://www.igalvan.es/og/base_hu_e4a25e7dfed04da3.png"/></item></channel></rss>