Cómo un backend de FastAPI + asyncpg comparte un solo Postgres chiquito con sus propios trabajadores en segundo plano y un segundo servicio, por qué el techo de conexiones, no el CPU, es lo que de verdad le pone tope a nuestro autoescalado, la caída en el cambio de hora que nos enseñó la cuenta, y una mirada honesta a RDS Proxy como la válvula de escape (incluyendo la trampa de asyncpg que lo puede dejar sin hacer nada).

TL;DR

La lección que replanteó todo el problema: en un RDS chico, tu cuenta máxima
de tareas la fija max_connections, no el CPU ni la memoria. Un autoescalado
que ignora el presupuesto de conexiones va a escalar directito hacia
QueuePool limit reached, o peor, FATAL: too many connections del mismo
Postgres.

El pool, y la cuenta escondida adentro de él

engine = create_async_engine(
    settings.DATABASE_URL,
    connect_args={"ssl": "prefer"},   # negocia TLS en RDS, texto plano en local
    pool_pre_ping=True,
    pool_size=8,
    max_overflow=12,                  # 8 + 12 = 20 conexiones por proceso
    pool_recycle=1800,
)

Veinte conexiones por proceso se ven modestas hasta que las multiplicas por
cada capa entre ellas y la base de datos:

  pool_size + max_overflow         = 20   por proceso de Python
  × 2 trabajadores de uvicorn      = 40   por tarea de Fargate
  × 2 durante un despliegue rolling = 80  (tarea vieja drenando + tarea nueva arrancando)
  + servicio de inteligencia (3 + 7) = 10 sobre la misma base de datos
  + alembic / ad-hoc / psql        ≈  unas pocas
  ----------------------------------------
  ≈ 87  ← el techo de la t3.micro, con ~0 de margen

Ese es el presupuesto entero, agotado, con una sola tarea de backend. El
tope de conexiones es por qué el backend no puede simplemente desiredCount: 5
— cinco tareas querrían 200 conexiones contra una base de datos que reparte

1. El tamaño del pool no es un ajuste de afinación de rendimiento aquí; es un ajuste de racionamiento.

Una sutileza que muerde: los trabajadores en segundo plano corren dentro del
proceso. main.py los lanza como tareas de asyncio dentro del mismo proceso
de uvicorn, así que jalan del mismo pool de 20 conexiones que los manejadores
de peticiones HTTP. No hay un pool de trabajadores aparte que dimensionar de
manera independiente, el ciclo del cron y la petición a la API compiten por
ranuras idénticas.

El día que se reventó

QueuePool limit of size 3 overflow 5 reached, connection timed out

El 2026-05-27 el pool estaba en 3/5, 8 conexiones por proceso. En el cambio
de hora, cuatro trabajadores de cron (ama, challenge, marketplace,
daily_token_digest) despertaron todos en el :00, cada uno abriendo una
sesión, mientras el tráfico normal de peticiones también jalaba del pool. Ocho
ranuras, muchos más de ocho prestatarios concurrentes, y las escrituras de
latido empezaron a vencerse por tiempo.

Dos cosas estaban mal, y solo una era "el pool está muy chico":

1. El pool de verdad estaba muy apretado para la carga combinada de peticiones + trabajadores. 3/5 no dejaba holgura para una estampida de planificadores que, por diseño, se disparan todos en la misma frontera del cron.
2. Los trabajadores no tenían jitter. Que todo se dispare exactamente en el :00 convierte trabajos independientes en una estampida sincronizada. (Escalonar los desfases del tick es la mitad más barata de la solución; este post trata de la mitad del pool.)

La solución fue subir el pool a 8/12 (20/proceso), elegido porque la cuenta
de conexiones de arriba decía que 20/proceso es el valor más grande que todavía
cabe en dos tareas debajo de 87 durante un despliegue. No es un número redondo;
es el número más grande que el techo permitía.

Mitigaciones que no son dimensionar

Dimensionar te mantiene debajo del tope. Otros tres ajustes evitan que las
conexiones que sí tienes se queden viejas o se fuguen:

pool_pre_ping=True,   # un SELECT 1 barato antes de entregar una conexión; reconecta si está muerta
pool_recycle=1800,    # cierra a la fuerza + reabre tras 30 min pase lo que pase

pool_pre_ping importa porque un proceso de larga vida (un ciclo de
trabajador, un manejador de WebSocket) puede quedarse sentado sobre una
conexión a través de un reinicio de RDS o de un timeout de inactividad de
NAT/firewall. Sin el pre-ping, la primera consulta después de que el socket
muere lanza excepción; con él, SQLAlchemy reconecta calladito. pool_recycle
es el respaldo que el pre-ping no puede dar, algunas conexiones muertas se ven
vivas para un SELECT 1 hasta que de verdad las usas, así que le ponemos tope
directo a la edad de la conexión.

Y en las pruebas, nada de pool:

# el conftest amarra la fábrica de sesiones a un engine con NullPool
engine = create_async_engine(TEST_DATABASE_URL, poolclass=NullPool)

Las conexiones agrupadas no sobreviven a que las pasen entre los event loops
por prueba que crea pytest-asyncio; NullPool abre y cierra una conexión por
cada checkout, lo cual es correcto (aunque más lento) para las pruebas y
esquiva una clase de errores de "atado a un loop distinto".

El hilo trampa

Como la siguiente caída de esta clase es invisible hasta que ya no lo es, la
cadena de la falla está conectada directo a una alarma:

// infra: convierte la cadena exacta del error en una métrica + alarma de CloudWatch
new logs.MetricFilter(this, "DbPoolExhaustedMetricFilter", {
  logGroup,
  filterPattern: logs.FilterPattern.literal('"QueuePool limit of size"'),
  metricName: "DbPoolExhausted",
  metricValue: "1",
});
// Alarma: ≥3 en 15 min → "el pool sigue muy chico; considera subir el RDS
// (t3.micro→small) ANTES de volver a subir pool_size, tope de RDS ≈87 conexiones"

El texto de la alarma codifica el árbol de decisión a propósito: cuando se
dispara, no vuelves a echar mano de pool_size, te quedaste sin
presupuesto de conexiones, así que el movimiento es una base de datos más
grande (o un proxy). Esa es la restricción alrededor de la que gira todo este
post.

El techo de verdad: el autoescalado está atado a las conexiones

Aquí está el problema estratégico. El backend autoescala por CPU
(scaleOnCpuUtilization). Pero el escalado por CPU y el presupuesto de
conexiones están en conflicto directo: en el momento en que la presión de CPU
nos escala de 1 tarea a 2, las conexiones brincan de ~40 a ~80; una tercera
tarea rebasaría 87 y Postgres empezaría a rechazar conexiones con
FATAL: too many connections, una caída causada por la cosa que debía
prevenirla.

Así que maxTasks está fijado en silencio por max_connections, no por la
carga. No podemos de verdad usar escalado horizontal para los picos de
tráfico, porque la base de datos no puede emitir las conexiones que las tareas
nuevas demandan. Subir la clase de la instancia de RDS compra margen lineal
(t3.small ≈ 2× las conexiones) pero cuesta dinero y solo mueve el muro. Lo
que quita el muro en lugar de moverlo es un proxy de conexiones.

RDS Proxy: la válvula de escape, y la trampa de asyncpg

RDS Proxy se sienta entre la app y Postgres y multiplexa: cientos de
conexiones de cliente comparten un pool chiquito de conexiones reales al
backend. La app abre conexiones a sus anchas; el proxy mantiene la cuenta real
de conexiones a la base de datos baja y estable. Eso desacopla la cuenta de
tareas de max_connections, el autoescalado por fin puede escalar por CPU sin
el muro de conexiones, y una estampida de trabajadores le presta del proxy en
lugar de a la base de datos.

Eso es el discurso de venta. Aquí está la parte que el discurso se calla, y la
razón por la que esto es una solución "posible" y no una ya publicada:

asyncpg + prepared statements = fijado de conexión. RDS Proxy solo puede
multiplexar cuando una sesión está "limpia". En el momento en que una sesión
hace algo con estado de conexión, un prepared statement, un SET, un advisory
lock, una tabla temporal, un LISTEN a nivel de sesión, el proxy fija ese
cliente a una sola conexión de backend por el resto de su vida y deja de
multiplexarlo. Y asyncpg, por default, cachea prepared statements para cada
consulta que corre. Tal como viene, asyncpg sobre RDS Proxy fija casi todo, y
pagaste por un proxy que se comporta como un paso directo, más un salto de
latencia.

Las mitigaciones, en orden de cuánto duelen:

# Deshabilita el caché de prepared statements de asyncpg para que RDS Proxy pueda multiplexar.
engine = create_async_engine(
    settings.DATABASE_URL,
    connect_args={
        "ssl": "require",                 # RDS Proxy exige TLS
        "statement_cache_size": 0,        # sin caché de prepared statements
        "prepared_statement_cache_size": 0,
    },
    poolclass=NullPool,   # deja que el PROXY haga el pool; el pooling del lado de la app ya es redundante
)

• statement_cache_size=0 impide que asyncpg cachee prepared statements, que es lo que mantiene las sesiones multiplexables. Costo: un pequeño sobrecosto por consulta de volver a preparar, normalmente un buen trato a cambio de conseguir multiplexar siquiera.
• Audita los otros disparadores de fijado. Nuestro conftest de CI usa pg_advisory_lock para montar la base de datos template, y algunos flujos usan estado a nivel de sesión, cada uno es un fijado. Detrás de un proxy quieres esos acotados con fuerza o movidos a nivel de transacción (pg_advisory_xact_lock) para que el fijado se libere al hacer commit.
• Deja que el proxy sea dueño del pool. Con RDS Proxy haciendo la multiplexación, el pool_size del lado de la app se vuelve doble-pooling; NullPool (o un pool diminuto) en la app y deja que el proxy racione.

La economía del proxy

RDS Proxy no es de capa gratuita. Se cobra por vCPU de la instancia de la
base de datos, más o menos $0.015 / vCPU-hora. Para una t3.micro de 2 vCPU
eso son ≈ $0.03/hr ≈ $21–22/mes, sobre un stack cuya premisa entera es
la Capa Gratuita de AWS. Así que la comparación de verdad es de tres vías:

La lectura honesta: a nuestra escala actual el muro todavía no aprieta. Una
tarea cabe, el subidón a 8/12 absorbió la estampida de trabajadores, y la
alarma no se ha disparado desde entonces. RDS Proxy se gana sus $21 el día que
de verdad necesitemos una segunda y tercera tarea para el tráfico, no antes.
Comprarlo ahora sería pagar una mensualidad para resolver un problema que
todavía no tenemos, y heredar la auditoría de fijado de asyncpg sin beneficio
presente. El disparador para adoptarlo es concreto: la alarma de escalado por
CPU y la alarma de presupuesto de conexiones disparándose en la misma
ventana, ese es el momento en que el CPU quiere más tareas y las conexiones
no las pueden suministrar, y el proxy es lo único que resuelve la
contradicción.

Lo que te diría

• Encuentra tu techo real primero. SELECT * FROM pg_settings WHERE name = 'max_connections'; luego réstale las ranuras reservadas. Cada decisión de pooling es río abajo de ese único número.
• El tamaño del pool es un ajuste de racionamiento en un RDS chico, no un ajuste de rendimiento. Dimensiónalo desde el presupuesto de conexiones (por-proceso × trabajadores × tareas × traslape-de-despliegue), no desde un benchmark.
• Los trabajadores dentro del proceso comparten el pool web. Si tus planificadores se disparan todos en la misma frontera del cron, son una estampida sincronizada contra el pool de peticiones. Agrega jitter; dimensiona para el pico.
• pre_ping + recycle no son opcionales para procesos asíncronos de larga vida detrás de un NAT/firewall o enfrente de una base de datos que se puede reiniciar.
• RDS Proxy quita el muro de conexiones, pero con asyncpg, pon statement_cache_size=0 y audita tus advisory locks, o fija y no hace nada. Mide la tasa de fijado (DatabaseConnectionsCurrentlySessionPinned) antes de cantar victoria.
• Compra el proxy cuando el muro apriete, no antes. La señal es el autoescalado por CPU y el agotamiento de conexiones peleándose en la misma ventana de 15 minutos.

Si te llevas una sola cosa: en un Postgres administrado chico, las conexiones
— no el CPU, son la unidad de escalado. Dimensiona tu pool desde ese
presupuesto, alarma sobre la cadena exacta de agotamiento, y trata a RDS Proxy
como la cosa que compras el día que el muro de conexiones empieza a costarte
tareas que de verdad necesitas.