El Caching de Connection Pooling de MySQL que Falló: Dentro de un Bug del 0.001% que Rompió Producción

Tu backend devuelve conjuntos de resultados vacíos para consultas que siempre devuelven datos. La tasa de error es del 0.001% — aproximadamente uno de cada 100,000 requests. Tu telemetría no muestra nada. Los traces no muestran nada. Y la única pista que tienes es que nunca ocurre cuando el caching está deshabilitado.

Esa es exactamente la situación en la que se encontró el equipo de Hyperdrive de Cloudflare al llevar el soporte de MySQL en su connection pooler a disponibilidad general. El bug que encontraron es una masterclass en cómo el caching de connection pooling de MySQL puede romperse silenciosamente cuando dos capas no se ponen de acuerdo sobre el formato de los bytes que viajan por el wire. Si ejecutas una capa de base de datos con pooling y caché para tu backend de juego — y deberías — este modo de fallo te aplica.

Este post desglosa el bug, los detalles del protocolo que lo hicieron posible, cómo detectarlo y remediarlo, y qué significa para la arquitectura de tu backend de juego.

Por Qué Existe el Connection Pooling

Establecer un handshake de TCP + TLS + MySQL hacia una base de datos requiere un mínimo de cinco round trips de red. Si tu servidor de juego abre una conexión nueva por request, estás pagando ese costo en cada lectura de leaderboard, cada fetch de save-game, cada consulta de inventario.

El pooling arregla esto manteniendo conexiones calientes abiertas y prestándolas. MySQL es más amigable con esto que Postgres — Postgres crea un proceso completo del OS por conexión, mientras que las conexiones de MySQL son comparativamente baratas — pero un juego popular con miles de jugadores concurrentes puede agotar los límites de conexión rápidamente.

El pooling introduce su propio problema, sin embargo: fuga de estado de sesión. Si la consulta del jugador A establece una variable de sesión y el jugador B recibe la misma conexión, tienes un bug de corrección. Los poolers resuelven esto con limpieza de conexión entre checkouts. MySQL proporciona un comando ligero para exactamente esto: COM_RESET_CONNECTION.

Y ahí es donde vive el primer bug sutil en esta historia.

Bug #1: Deriva de Codificación Después de Resets de Conexión

El equipo de Hyperdrive negoció utf8 en el handshake inicial. Eso funcionó — hasta que los jugadores empezaron a usar emojis en el chat y en los nombres de personaje, y los datos volvieron distorsionados.

El problema: utf8 en MySQL es un alias obsoleto para utf8mb3, que soporta solo 1–3 bytes por code point Unicode. UTF-8 completo (incluyendo emojis, extensiones CJK, y la mayoría de escrituras no latinas que usará tu base de jugadores global) requiere hasta 4 bytes por code point. La solución es negociar utf8mb4 en su lugar.

Pero aquí está la trampa que atrapa a casi todos:

-- Startup handshake: negotiate utf8mb4. All good.
-- Then, between checkouts, the pooler runs:
COM_RESET_CONNECTION;
-- Surprise: the server does NOT reset to the negotiated charset.
-- It resets to the SERVER DEFAULT, e.g. latin1.

COM_RESET_CONNECTION no restaura la conexión al character set que negociaste al inicio. Se resetea al charset por defecto del servidor — que en muchas instancias de MySQL sigue siendo latin1. Después del primer reset, cada conexión agrupada se degrada silenciosamente a una codificación de los años 90.

La remediación: vuelve a aplicar tu configuración de sesión después de cada reset, no solo al inicio:

COM_RESET_CONNECTION;
SET NAMES utf8mb4 COLLATE utf8mb4_unicode_ci;
SET SESSION time_zone = '+00:00';

Regla general: trata la conexión como completamente no configurada después de cada reset, y vuelve a afirmar todo lo que te importa. Cualquier cosa que configures una vez al conectar eventualmente se perderá.

Bug #2: El Bug de Respuesta Vacía del 0.001%

Este es el que tomó días encontrar. Un cliente de alto volumen reportó una tasa pequeña pero consistente de respuestas vacías a consultas donde se garantizaban respuestas no vacías. El error ocurría alrededor del 0.001% de las veces — demasiado raro para capturar un trace de extremo a extremo de manera fiable, demasiado frecuente para ignorarlo.

El equipo revisó telemetría, aumentó las tasas de trace, buscó anomalías de red. Nada. La única pista que lo resolvió: el bug solo ocurría en instancias con caching habilitado.

La Arquitectura Que Lo Hizo Posible

Hyperdrive usa una topología dividida:

• Nodo cliente — se ejecuta cerca del Worker, maneja el caché local, reenvía consultas hacia adelante.
• Nodo endpoint — se ejecuta en el centro de datos más cercano a la base de datos de origen, mantiene el connection pool real.

Ambos nodos usan la caché del CDN local a su centro de datos. Cuando se ejecutan en el mismo centro de datos, comparten una sola caché. Esa compartición es una victoria de rendimiento — pero conlleva una condición oculta: ambos nodos deben almacenar en caché exactamente los mismos bytes para la misma respuesta de consulta.

El Desajuste de Protocolo

El protocolo cliente/servidor de MySQL tiene una Connection Phase donde el cliente y el servidor negocian capacidades — características opcionales como CLIENT_DEPRECATE_EOF, que cambia cómo se terminan los result sets:

• Sin CLIENT_DEPRECATE_EOF: paquete EOF después de las definiciones de columna, luego otro EOF al final del result set.
• Con él: el EOF de metadatos se omite y el EOF final se convierte en un paquete OK.

Hyperdrive soporta la capacidad y la negocia con el servidor MySQL de origen. Pero la librería del cliente al otro lado — por ejemplo, mysql2 para Node.js, que actualmente no soporta CLIENT_DEPRECATE_EOF — puede que no. Así que Hyperdrive debe traducir: reescribir los result sets para insertar paquetes EOF, convertir paquetes OK de vuelta a EOFs, para que los bytes coincidan con lo que el driver del Worker espera.

La consecuencia: los bytes que Hyperdrive escribe de vuelta al cliente están en un formato diferente al de los bytes que recibe del servidor de origen.

La Suposición Incorrecta

Cuando se implementó el caching del cliente para Postgres, el equipo incorporó una suposición: puedes almacenar en caché exactamente los bytes que escribiste de vuelta al cliente. Para el protocolo wire de Postgres, eso era cierto. Para MySQL, no lo es.

Ahora ensambla el fallo:

1. El Endpoint procesa la consulta Q, almacena los bytes de respuesta en el formato de capacidades de Hyperdrive en la caché compartida.
2. El Cliente (mismo centro de datos) recibe un request para Q, encuentra la entrada cacheada, y se la sirve al Worker sin traducir capacidades — porque los bytes parecen ya escritos para el Worker.
3. El driver del Worker, que nunca negoció CLIENT_DEPRECATE_EOF, malinterpreta el result set terminado en OK — produciendo resultados vacíos, cuelgues, o desyncs de protocolo.

El bug solo se dispara cuando Cliente y Endpoint están colocalizados y uno lee la entrada de caché del otro. Por eso era 0.001% e invisible para el tracing ordinario. Es el equivalente wire-protocol de un bug de desync — dos componentes con suposiciones diferentes sobre el estado compartido. Si alguna vez has depurado una divergencia de estado entre predicción del cliente y autoridad del servidor, la forma de este fallo te resultará familiar; es la misma clase de problema descrito en cómo arreglar el problema de replicación RPC de Unreal Engine que rompe tus estados, solo que en la capa wire de la base de datos.

La solución, conceptualmente: almacenar en caché en formato canónico (lo que envió el origen), y traducir a las capacidades del cliente que solicita al momento de leer. Nunca almacenes en caché bytes post-traducción cuando la traducción depende de la negociación por cliente.

Runbook: Detectando Corrupción de Caché en Tu Propio Stack

Si ejecutas un pooler o capa de caché frente a MySQL (o cualquier cosa con un protocolo wire con estado), así es como aplicar este postmortem.

Detección

• Correlaciona errores con topología. El bug solo aparecía en instancias donde Cliente y Endpoint compartían centro de datos y caché. Registra qué nodo sirvió cada respuesta y si vino de caché. Si la tasa de error correlaciona con cache hits, sospecha un desajuste de formato entre escritor y lector.
• Caza errores raros pero consistentes, no picos. Una tasa de error del 0.001% nunca activa alertas. Configura una consulta en tu seguimiento de errores para ocurrencias repetidas de la misma firma independientemente del volumen. La consistencia a baja tasa es una señal más fuerte de un bug lógico que un pico correlacionado con tráfico.
• Prueba con asimetría de capacidades deliberadamente. Conecta un cliente de prueba con CLIENT_DEPRECATE_EOF y otro sin él, habilita el caching, y golpea consultas idénticas. La mayoría de los bugs de traducción de protocolo salen a la superficie en minutos bajo esta asimetría.

Remediación

• Canonicaliza las entradas de caché. Almacena el formato de respuesta crudo del origen; traduce en la lectura. Esa es la solución correcta para cualquier pooler cuyos clientes tengan capacidades heterogéneas.
• Re-afirma el estado de sesión después de resets. Como se mostró arriba, COM_RESET_CONNECTION restaura los valores por defecto del servidor, no tus ajustes negociados.
• Versiona tus cache keys. Si cambias cualquier comportamiento de protocolo (capacidades, codificación, framing de respuesta), incluye una versión de formato en la cache key para que entradas antiguas no puedan ser servidas por código nuevo a mitad de despliegue.

# Cache key hygiene, in pseudocode
def cache_key(query_normalized: str, schema_version: int, format_version: int) -> str:
    # format_version bumps whenever wire-format handling changes,
    # preventing stale-format entries from poisoning new deploys
    return sha256(f"{schema_version}:{format_version}:{query_normalized}")

Prevención

• Escribe pruebas de conformidad de protocolo wire contra dos librerías de cliente, no una. La brecha de CLIENT_DEPRECATE_EOF solo fue visible porque un driver popular de Node.js no lo soportaba.
• No asumas nada sobre "los mismos bytes" entre capas. Cualquier componente que reescriba mensajes no debe asumir que su salida es byte-idéntica a su entrada.
• Prueba de carga con caché habilitado desde el día uno. El equipo de Hyperdrive validó la fiabilidad durante meses antes de que el bug específico de caché saliera a la luz — porque la intersección de características (pooling × caching × traducción de capacidades) es donde viven los bugs raros.

Cinco Mejores Prácticas para Pooling y Caching en Backends de Juegos

1. Siempre negocia utf8mb4, nunca utf8. Los nombres de jugador, el chat, y los datos de guardado contendrán caracteres de 4 bytes. Luego re-afirma SET NAMES utf8mb4 después de cada COM_RESET_CONNECTION, porque el reset restaura los valores por defecto del servidor, no tu handshake.
2. Almacena en caché datos canónicos, no datos formateados para el cliente. Si cualquier capa transforma una respuesta antes de enviarla, los bytes transformados nunca deben entrar en una caché compartida. Almacena el formato del origen; traduce por lector.
3. Añade versiones de formato a las cache keys. Un cambio de una línea, te salva de entradas con protocolo obsoleto durante despliegues continuos.
4. Alerta sobre la consistencia del error, no solo sobre la tasa de error. Una firma recurrente del 0.001% sin correlación con tráfico es un bug lógico. Un pico correlacionado con tráfico es un problema de capacidad. Enrútalos de manera diferente.
5. Prueba clientes con capacidades no coincidentes. La corrección de tu pooler depende de manejar cada librería de cliente con la que tu equipo (o los usuarios de tu SDK) puedan conectarse.

La Lección de Arquitectura de Backend

La lección más profunda aquí no es sobre MySQL en absoluto. Es sobre sistemas en capas con negociación por par. En el momento en que insertas un middlebox — un pooler, un proxy, una caché — que habla el protocolo en ambos lados, heredas la obligación de traducir fielmente y de almacenar en caché solo formatos que sean universalmente válidos. Postgres funcionó; MySQL se rompió; nada sobre la lógica de caching estaba mal excepto una suposición heredada de un protocolo diferente.

Para un estudio de juegos, esto es un argumento fuerte contra construir tu propio pooler más capa de caché a mano. El esfuerzo de ingeniería para lograr que el camino feliz funcione es quizás una semana; el esfuerzo para lograr que los caminos raros estén bien — negociación de capacidades, deriva de codificación, co-localización de caché — es lo que tomó a un equipo de infraestructura dedicado días de investigación para cazar un solo bug del 0.001%. La propia admisión de Cloudflare vale la pena repetirla: la diferencia entre beta y GA era "solo 20 correcciones de bugs en una gabardina."

Si tu backend de juego necesita persistencia fiable sin que tú mantengas un pooler, un esquema de invalidación de caché, y una capa de traducción de protocolo, ahí es donde un Backend-as-a-Service demuestra su valor. horizOn maneja Cloud Save vinculado a la cuenta con lecturas y escrituras conscientes de revisión — tu cliente resuelve conflictos, y te saltas todo el campo minado de corrección de conexiones agrupadas más caché para los datos de los jugadores. Combínalo con leaderboards y configuración remota, y los problemas de latencia de consulta discutidos en este post dejan de ser tu problema.

Siguiente paso: audita hoy tu propia configuración de pooler. Verifica tres cosas: el charset negociado, si el estado de sesión se re-afirma después de resets de conexión, y si tu caché almacena bytes canónicos o traducidos. Si no puedes responder las tres en diez minutos, tienes trabajo por hacer — y si prefieres no hacerlo en absoluto, echa un vistazo a horizOn y mira si su Cloud Save y leaderboards cubren lo que tu capa de base de datos hace actualmente a mano.

---

Fuente: Inside Hyperdrive: How we solved a rare Hyperdrive MySQL caching bug