MySQL Connection Pooling Caching schiefgelaufen: Innenansicht eines 0,001-%-Bugs, der die Produktion lahmlegte

Dein Backend liefert leere Ergebnismengen für Abfragen, die immer Daten zurückgeben. Die Fehlerrate liegt bei 0,001 % – also etwa einer von 100.000 Requests. Deine Telemetrie zeigt nichts. Traces zeigen nichts. Und der einzige Hinweis, den du hast, ist, dass es nie passiert, wenn Caching deaktiviert ist.

Genau in dieser Situation befand sich das Hyperdrive-Team von Cloudflare, als es die MySQL-Unterstützung in seinem Connection Pooler zur allgemeinen Verfügbarkeit brachte. Der gefundene Bug ist eine Meisterklasse darin, wie MySQL Connection Pooling Caching lautlos kaputtgehen kann, wenn zwei Ebenen sich nicht über das Format der Bytes einig sind, die über die Leitung wandern. Wenn du für dein Game-Backend eine gepoolte, gecachte Datenbankschicht betreibst – und das solltest du –, betrifft dich dieser Fehlermodus.

Dieser Beitrag zerlegt den Bug, die Protokolldetails, die ihn möglich machten, wie man ihn erkennt und behebt – und was er für deine eigene Game-Backend-Architektur bedeutet.

Warum Connection Pooling überhaupt existiert

Ein TCP- + TLS- + MySQL-Handshake zu einer Datenbank erfordert mindestens fünf Netzwerk-Round-Trips. Wenn dein Game-Server pro Request eine neue Verbindung öffnet, zahlst du diesen Preis bei jedem Leaderboard-Read, jedem Save-Game-Abruf und jeder Inventar-Abfrage.

Pooling behebt das, indem warme Verbindungen offen gehalten und ausgeliehen werden. MySQL ist dafür freundlicher als Postgres – Postgres erzeugt pro Verbindung einen ganzen OS-Prozess, während MySQL-Verbindungen vergleichsweise günstig sind –, aber ein beliebtes Spiel mit Tausenden gleichzeitigen Spielern kann Verbindungslimits trotzdem schnell erschöpfen.

Pooling bringt allerdings ein eigenes Problem mit sich: Session-State-Leakage. Wenn die Abfrage von Spieler A eine Session-Variable setzt und Spieler B dieselbe Verbindung bekommt, hast du einen Korrektheitsbug. Pooler lösen das mit Connection Cleanup zwischen den Checkouts. MySQL bietet dafür ein leichtgewichtiges Kommando: COM_RESET_CONNECTION.

Und genau hier lebt der erste subtile Bug dieser Geschichte.

Bug #1: Encoding-Drift nach Connection Resets

Das Hyperdrive-Team handelte beim Startup-Handshake utf8 aus. Das funktionierte – bis Spieler anfingen, Emojis in Chat und Charakternamen zu verwenden, und die Daten verstümmelt zurückkamen.

Das Problem: utf8 ist in MySQL ein veralteter Alias für utf8mb3, das nur 1–3 Bytes pro Unicode-Codepoint unterstützt. Volles UTF-8 (einschließlich Emoji, CJK-Erweiterungen und der meisten nicht-lateinischen Schriften, die deine globale Spielerbasis verwenden wird) benötigt bis zu 4 Bytes pro Codepoint. Die Lösung ist, stattdessen utf8mb4 auszuhandeln.

Aber hier ist die Falle, in die fast alle tappen:

-- 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 stellt die Verbindung nicht auf den Zeichensatz zurück, den du beim Start ausgehandelt hast. Es setzt auf den Standard-Zeichensatz des Servers zurück – der auf vielen MySQL-Instanzen immer noch latin1 ist. Nach dem ersten Reset degradiert jede gepoolte Verbindung lautlos auf eine Encoding-Ära der 1990er-Jahre.

Die Abhilfe: Wende deine Session-Konfiguration nach jedem Reset erneut an, nicht nur beim Start:

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

Faustregel: Behandle die Verbindung nach jedem Reset als vollständig unkonfiguriert und setze alles, was dir wichtig ist, erneut durch. Alles, was du nur einmal beim Verbindungsaufbau setzt, geht irgendwann verloren.

Bug #2: Der 0,001-%-Empty-Response-Bug

Das ist derjenige, dessen Suche Tage dauerte. Ein Kunde mit hohem Volumen meldete eine kleine, aber konstante Rate leerer Abfrageantworten, obwohl nicht-leere Antworten garantiert waren. Der Fehler trat in etwa 0,001 % der Fälle auf – zu selten, um zuverlässig einen End-to-End-Trace zu erfassen, zu häufig, um ihn zu ignorieren.

Das Team durchforstete Telemetrie, erhöhte Trace-Raten, suchte nach Netzwerkanomalien. Nichts. Der eine Hinweis, der den Fall löste: Der Bug trat nur auf Instanzen mit aktiviertem Caching auf.

Die Architektur, die das möglich machte

Hyperdrive verwendet eine Split-Topologie:

• Client-Node – läuft nahe am Worker, übernimmt lokales Caching und leitet Abfragen weiter.
• Endpoint-Node – läuft im Rechenzentrum, das der Ursprungsdatenbank am nächsten ist, und hält den eigentlichen Connection Pool.

Beide Nodes nutzen den CDN-Cache ihres Rechenzentrums. Wenn sie im selben Rechenzentrum laufen, teilen sie sich einen Cache. Dieses Teilen ist ein Performance-Gewinn – aber es hat eine versteckte Vorbedingung: Beide Nodes müssen für dieselbe Abfrageantwort exakt dieselben Bytes cachen.

Das Protokoll-Mismatch

Das MySQL-Client/Server-Protokoll hat eine Connection Phase, in der Client und Server Capabilities aushandeln – optionale Features wie CLIENT_DEPRECATE_EOF, das ändert, wie Resultsets beendet werden:

• Ohne CLIENT_DEPRECATE_EOF: EOF-Paket nach den Spaltendefinitionen, dann ein weiteres EOF am Ende des Resultsets.
• Mit aktiviertem Flag: Das Metadaten-EOF entfällt und das abschließende EOF wird zu einem OK-Paket.

Hyperdrive unterstützt diese Capability und handelt sie mit dem MySQL-Ursprungsserver aus. Aber die Client-Bibliothek auf der anderen Seite – zum Beispiel mysql2 für Node.js, das CLIENT_DEPRECATE_EOF derzeit nicht unterstützt – tut das möglicherweise nicht. Hyperdrive muss also übersetzen: Resultsets umschreiben, um EOF-Pakete einzufügen, OK-Pakete zurück in EOFs konvertieren, damit die Bytes dem entsprechen, was der Worker-Treiber erwartet.

Die Konsequenz: Die Bytes, die Hyperdrive an den Client zurückschreibt, haben ein anderes Format als die Bytes, die es vom Ursprungsserver erhält.

Die fehlerhafte Annahme

Als das Client-Caching für Postgres implementiert wurde, baute das Team eine Annahme ein: Man kann exakt die Bytes cachen, die man an den Client zurückgeschrieben hat. Für das Postgres-Wire-Protokoll stimmte das. Für MySQL nicht.

Jetzt füge den Fehler zusammen:

1. Der Endpoint bedient Abfrage Q und cached die Antwort-Bytes im Hyperdrive-Capability-Format in den gemeinsamen Cache.
2. Der Client (gleiches Rechenzentrum) erhält einen Request für Q, findet den Cache-Eintrag und liefert ihn an den Worker aus, ohne Capabilities zu übersetzen – weil die Bytes so aussehen, als wären sie bereits für den Worker geschrieben worden.
3. Der Worker-Treiber, der CLIENT_DEPRECATE_EOF nie ausgehandelt hat, interpretiert das OK-terminierte Resultset falsch – mit leeren Ergebnissen, Hangs oder Protokoll-Desyncs als Folge.

Der Bug feuert nur, wenn Client und Endpoint am selben Ort liegen und einer den Cache-Eintrag des anderen liest. Deshalb war er 0,001 % und für normales Tracing unsichtbar. Es ist das Wire-Protokoll-Äquivalent eines Desync-Bugs – zwei Komponenten mit unterschiedlichen Annahmen über gemeinsamen State. Wenn du jemals State-Divergenz zwischen Client-Prädiktion und Server-Autorität debuggt hast, kommt dir die Form dieses Fehlers bekannt vor; es ist dieselbe Problemklasse, die in Behebung des Unreal-Engine-RPC-Replikationsproblems, das deine States zerstört beschrieben wird – nur auf der Datenbank-Wire-Ebene.

Die Lösung, konzeptionell: Im kanonischen Format cachen (also das, was der Ursprung gesendet hat) und beim Lesen in die Capabilities des anfragenden Clients übersetzen. Cache niemals Bytes nach der Übersetzung, wenn die Übersetzung von der Verhandlung pro Client abhängt.

Runbook: Cache-Korruption im eigenen Stack erkennen

Wenn du einen Pooler oder eine Cache-Schicht vor MySQL betreibst (oder vor irgendetwas mit einem zustandsbehafteten Wire-Protokoll), erfährst du hier, wie du dieses Postmortem anwendest.

Erkennung

• Korreliere Fehler mit der Topologie. Der Bug trat nur auf Instanzen auf, in denen Client und Endpoint sich ein Rechenzentrum und einen Cache teilten. Protokolliere, welcher Node jede Antwort ausgeliefert hat und ob sie aus dem Cache kam. Wenn die Fehlerrate mit Cache-Hits korreliert, vermute einen Format-Mismatch zwischen Schreiber und Leser.
• Jage seltene, aber konsistente Fehler, keine Spikes. Eine Fehlerrate von 0,001 % löst niemals Alerts aus. Richte in deinem Error Tracking eine Abfrage auf wiederholte Vorkommen derselben Signatur ein, unabhängig vom Volumen. Konsistenz bei niedriger Rate ist ein stärkeres Signal für einen Logikbug als ein verkehrskorrelierter Spike.
• Teste absichtlich mit Capability-Asymmetrie. Verbinde einen Testclient mit CLIENT_DEPRECATE_EOF und einen ohne, aktiviere Caching und feuere identische Abfragen ab. Die meisten Protokoll-Übersetzungsbugs tauchen unter dieser Asymmetrie innerhalb von Minuten auf.

Behebung

• Kanonisiere Cache-Einträge. Speichere das rohe Antwortformat des Ursprungs; übersetze beim Lesen. Das ist der richtige Fix für jeden Pooler, dessen Clients heterogene Capabilities haben.
• Setze Session-State nach Resets erneut durch. Wie oben gezeigt, stellt COM_RESET_CONNECTION die Server-Standards wieder her, nicht deine ausgehandelten Einstellungen.
• Versioniere deine Cache-Keys. Wenn du irgendein Protokollverhalten änderst (Capabilities, Encoding, Response-Framing), nimm eine Formatversion in den Cache-Key auf, damit alte Einträge während eines Deploys nicht von neuem Code ausgeliefert werden.

# 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}")

Vorbeugung

• Schreibe Wire-Protokoll-Konformitätstests gegen zwei Client-Bibliotheken, nicht nur eine. Die CLIENT_DEPRECATE_EOF-Lücke war nur sichtbar, weil ein populärer Node.js-Treiber sie nicht unterstützte.
• Geh niemals davon aus, dass Bytes über Ebenen hinweg „dieselben“ sind. Jede Komponente, die Nachrichten umschreibt, darf nicht annehmen, dass ihre Ausgabe byte-identisch mit ihrer Eingabe ist.
• Mache vom ersten Tag an Lasttests mit aktiviertem Cache. Das Hyperdrive-Team validierte die Zuverlässigkeit monatelang, bevor der cache-spezifische Bug auftauchte – denn an der Schnittstelle von Features (Pooling × Caching × Capability-Übersetzung) leben seltene Bugs.

Fünf Best Practices für Pooling und Caching in Game-Backends

1. Handel immer utf8mb4 aus, niemals utf8. Spielernamen, Chat und Save-Daten werden 4-Byte-Zeichen enthalten. Setze außerdem nach jedem COM_RESET_CONNECTION erneut SET NAMES utf8mb4 durch, denn der Reset stellt Server-Standards wieder her, nicht deinen Handshake.
2. Cache kanonische Daten, nicht client-formatierte Daten. Wenn eine Ebene eine Antwort vor dem Senden transformiert, dürfen die transformierten Bytes niemals in einen gemeinsamen Cache gelangen. Speichere das Ursprungsformat; übersetze pro Leser.
3. Füge Cache-Keys Formatversionen hinzu. Eine Änderung in einer Zeile bewahrt dich vor Einträgen mit veraltetem Protokoll während Rolling Deploys.
4. Alarme auf Fehler-Konsistenz, nicht nur auf Fehler-Rate. Eine wiederkehrende 0,001-%-Signatur ohne Verkehrskorrelation ist ein Logikbug. Ein verkehrskorrelierter Spike ist ein Kapazitätsproblem. Leite sie unterschiedlich weiter.
5. Teste Clients mit nicht übereinstimmenden Capabilities. Die Korrektheit deines Poolers hängt davon ab, dass er jede Client-Bibliothek verarbeitet, mit der dein Team (oder deine SDK-Nutzer) sich verbinden könnte.

Die Lektion für die Backend-Architektur

Die tiefste Lektion hier hat gar nicht mit MySQL zu tun. Es geht um geschichtete Systeme mit Pro-Peer-Verhandlung. In dem Moment, in dem du eine Middlebox einfügst – einen Pooler, einen Proxy, einen Cache –, die auf beiden Seiten Protokoll spricht, übernimmst du die Verpflichtung, treu zu übersetzen und nur Formate zu cachen, die universell gültig sind. Postgres funktionierte; MySQL brach; an der Caching-Logik war nichts falsch außer einer Annahme, die aus einem anderen Protokoll geerbt wurde.

Für ein Game-Studio ist das ein starkes Argument gegen eine selbst gebaute Pooler-plus-Cache-Schicht. Der Engineering-Aufwand, um den Happy Path zum Laufen zu bringen, ist vielleicht eine Woche; der Aufwand, um die seltenen Pfade richtig hinzubekommen – Capability-Verhandlung, Encoding-Drift, Cache-Ko-Lokation –, hat ein dediziertes Infrastruktur-Team tagelange Untersuchungen gekostet, um einen einzigen 0,001-%-Bug aufzuspüren. Cloudflares eigene Einsicht ist es wert, wiederholt zu werden: Der Unterschied zwischen Beta und GA war „nur 20 Bugfixes in einem Trenchcoat“.

Wenn dein Game-Backend zuverlässige Persistenz braucht, ohne dass du einen Pooler, ein Cache-Invalidierungsschema und eine Protokoll-Übersetzungsschicht wartest, dann verdient ein Backend-as-a-Service hier sein Geld. horizOn übernimmt accountgebundene Cloud Saves mit revisionsbewussten Reads und Writes – dein Client löst Konflikte auf, und du überspringst das gesamte Korrektheits-Minenfeld aus gepoolter Verbindung plus Cache für Spielerdaten. Kombiniere es mit Leaderboards und Remote Configuration, und die in diesem Beitrag diskutierten Query-Latenzprobleme hören größtenteils auf, dein Problem zu sein.

Nächster Schritt: Prüfe noch heute deine eigene Pooler-Konfiguration. Check drei Dinge – den ausgehandelten Zeichensatz, ob Session-State nach Connection Resets erneut durchgesetzt wird, und ob dein Cache kanonische oder übersetzte Bytes speichert. Wenn du nicht alle drei in zehn Minuten beantworten kannst, hast du Arbeit vor dir – und wenn du sie lieber ganz vermeiden willst, wirf einen Blick auf horizOn und schau, ob dessen Cloud Saves und Leaderboards abdecken, was deine Datenbankschicht derzeit von Hand erledigt.

---

Quelle: Inside Hyperdrive: So haben wir einen seltenen Hyperdrive-MySQL-Caching-Bug gelöst