Cómo una incompatibilidad de capacidades rompió la caché de MySQL en Cloudflare Hyperdrive

Cloudflare ha anunciado la disponibilidad general del soporte para MySQL en Hyperdrive, su agrupador de conexiones de base de datos para Workers. Este lanzamiento sigue a un periodo beta durante el cual los ingenieros identificaron y resolvieron un sutil error de caché que causaba respuestas de consulta vacías ocasionalmente. Esta corrección garantiza que el servicio cumpla con su objetivo de disponibilidad del 99,99% para cargas de trabajo de MySQL.

Qué ocurrió

Hyperdrive se lanzó inicialmente con soporte para Postgres, permitiendo que los Workers sin servidor compartieran conexiones activas a bases de datos y almacenaran en caché los resultados de consultas globalmente. Cuando el soporte para MySQL entró en fase beta el año pasado, el equipo buscó igualar la fiabilidad de su implementación en Postgres. Durante esta fase de pruebas, clientes de alto volumen reportaron una tasa de error consistente pero rara, en la que las consultas devolvían resultados vacíos en lugar de los datos esperados. Este problema ocurría aproximadamente en el 0,001% de las solicitudes, lo que dificultaba su reproducción y rastreo.

La investigación reveló que el problema era específico de las instancias de Hyperdrive con la caché habilitada. Los ingenieros rastrearon el error hasta la forma en que Hyperdrive maneja el protocolo cliente/servidor de MySQL, específicamente en lo relativo a la negociación de capacidades. A diferencia de Postgres, MySQL utiliza banderas de capacidad para determinar cómo se formatean y terminan los conjuntos de resultados. Una discrepancia entre lo que esperaba el controlador del Worker y lo que Hyperdrive había guardado en caché provocaba respuestas corruptas o ilegibles cuando los nodos compartían una caché.

Para alcanzar la disponibilidad general, el equipo implementó veinte correcciones de errores, incluyendo ajustes en la codificación de juegos de caracteres y en los comportamientos de reinicio de conexión. La corrección más crítica abordó la lógica de caché para garantizar que todos los resultados de consultas almacenados utilicen un formato canónico. Con estos cambios desplegados, los errores de respuesta vacía desaparecieron y el servicio alcanzó sus objetivos de fiabilidad.

Cómo funciona

Hyperdrive utiliza una arquitectura dividida compuesta por un nodo Cliente y un nodo Endpoint. El Cliente se ejecuta cerca del Worker, gestionando las solicitudes locales y la caché, mientras que el Endpoint está más cerca de la base de datos de origen, administrando el grupo de conexiones. Ambos nodos utilizan la caché local de la CDN de Cloudflare. Cuando el Cliente y el Endpoint residen en el mismo centro de datos, comparten esta caché para mejorar el rendimiento al servir consultas repetidas sin acceder a la base de datos.

El protocolo de MySQL depende de la negociación de capacidades durante la fase de conexión. Una capacidad clave es CLIENT_DEPRECATE_EOF, que cambia la forma en que se terminan los conjuntos de resultados. Los servidores modernos omiten un paquete EOF después de las definiciones de columnas y reemplazan el EOF final con un paquete OK si se negocia esta capacidad. Sin embargo, algunas bibliotecas de cliente, como mysql2 para Node.js, no admiten esta bandera. Hyperdrive debe traducir las respuestas entre el formato del servidor de origen y el formato esperado por el Worker.

El error surgió porque la capa de caché asumía que podía almacenar exactamente los bytes enviados al Worker. Si el Endpoint guardaba en caché una respuesta utilizando las capacidades internas de Hyperdrive, pero el Cliente la recuperaba y enviaba esos bytes crudos a un Worker que esperaba un formato diferente, el Worker malinterpretaría los datos. Inversamente, si el Cliente guardaba en caché bytes traducidos, el Endpoint podría recuperarlos y fallar al procesarlos correctamente. La corrección asegura que solo se escriba en la caché compartida una versión canónica de la respuesta, codificada con las capacidades de Hyperdrive.

Detalles clave

• Hyperdrive para MySQL ya está disponible generalmente, habiendo salido de la fase beta.
• El servicio apunta a una disponibilidad del 99,99% para conexiones de cliente desde Workers.
• Un error raro causaba que el 0,001% de las consultas cacheadas devolvieran resultados vacíos o se colgaran.
• El problema derivaba de un manejo incompatible de la capacidad CLIENT_DEPRECATE_EOF.
• Corregir el error requería asegurar una codificación de bytes canónica en la caché compartida de la CDN.
• Correcciones adicionales abordaron la codificación utf8mb4 y los reinicios de estado COM_RESET_CONNECTION.

Por qué importa

Para los desarrolladores que construyen sobre plataformas sin servidor, la gestión de conexiones a bases de datos es un desafío persistente. Establecer nuevas conexiones para cada solicitud añade latencia significativa y consume recursos. Los agrupadores de conexiones como Hyperdrive mitigan esto manteniendo las conexiones activas, pero introducen complejidad en la traducción de protocolos. Comprender cómo estas herramientas manejan los protocolos de red ayuda a los ingenieros a depurar problemas oscuros que surgen al mezclar diferentes bibliotecas de cliente y versiones de bases de datos.

Este incidente destaca los riesgos de asumir uniformidad de protocolo entre diferentes sistemas de bases de datos. Aunque tanto Postgres como MySQL usan SQL, sus protocolos de red subyacentes difieren significativamente. Los ingenieros que integran infraestructuras multi-protocolo deben ser conscientes de que las capas de caché pueden necesitar normalizar formatos de datos para prevenir desincronizaciones. Ignorar estos matices puede llevar a fallos intermitentes difíciles de reproducir en entornos de desarrollo local.

Además, la dependencia de cachés compartidas en sistemas distribuidos requiere garantías estrictas de consistencia. Cuando múltiples componentes leen y escriben en la misma caché, deben estar de acuerdo en el esquema de datos. En este caso, la falta de un formato canónico hizo que la caché se convirtiera en una fuente de corrupción en lugar de rendimiento. Esta lección se aplica ampliamente a cualquier sistema que use caché intermedia para la traducción de protocolos.

Qué puedes hacer

• Actualiza a la versión de disponibilidad general de Hyperdrive para MySQL para beneficiarte de las correcciones de estabilidad.
• Verifica que tu biblioteca de cliente MySQL soporte utf8mb4 para evitar problemas de codificación de caracteres con emojis o caracteres especiales.
• Comprueba si tu controlador de cliente soporta CLIENT_DEPRECATE_EOF para entender cómo se terminan los conjuntos de resultados en tu aplicación.
• Monitorea tu aplicación en busca de resultados de consultas vacíos intermitentes si estás usando un controlador MySQL personalizado o antiguo.
• Usa la CLI wrangler para crear nuevas instancias de Hyperdrive para bases de datos compatibles con MySQL como PlanetScale.
• Revisa tu lógica de reinicio de conexiones para asegurar que el estado de sesión no se filtre entre solicitudes en entornos agrupados.