Cloudflare Hyperdrive Serves MySQL From One Canonical Copy of a Query Result

TL;DR

• Hyperdrive is a distributed connection pooler that Cloudflare runs for Workers, holding warm database connections on the company's network and caching query results in its global cache, so Worker requests share connections that are already open.
• MySQL support in Hyperdrive reached general availability on 14 October 2026, roughly eighteen months after the beta that added MySQL to Postgres-only support.
• The story behind the release is a consistency bug between the two nodes Hyperdrive runs: a Client beside the Worker and an Endpoint beside the database, each with the data-centre cache they can share.
• The disagreement was about encoding. Each node cached the bytes it wrote back to the Worker, so a result stored in one node's format could be read by the other node and translated wrongly.
• The failure surfaced as empty query results on about 0.001% of requests for one high-volume customer, and it appeared once caching was enabled, which pointed the investigation at the pooled path.
• The fix stores one canonical copy of every result, encoded in Hyperdrive's own capabilities, whichever node writes it, and the success rate for client connections reached 99.99% after it shipped.
• General availability also carries the smaller items: twenty fixes in total, among them a handshake that negotiated utf8, an alias limited to three bytes per code point, which broke four-byte characters such as emoji.

What Hyperdrive does between a Worker and a database

A Worker runs at the edge, and the database it needs sits in one region. Establishing a connection between the two costs at least five network round trips on Cloudflare's own count, and a platform that opened one per request would spend more time on handshakes than on queries. Hyperdrive exists to keep that connection warm: the Client node runs alongside the Worker's machine, the Endpoint node runs near the database, and the Endpoint holds a pool of open connections that many Worker requests share.

The product also caches. Results for frequently repeated queries can live in the CDN cache local to each data centre, which is where the vendor's own headline numbers come from: three times faster queries from pooling, up to a hundred times on repeated queries, and cached results in under five milliseconds. A connection string swap is the documented migration path, with mysql2 and mysql among the supported Node.js drivers.

Two nodes, one cache, and an encoding disagreement

The architecture puts a cache at each end, and when a Client and its Endpoint sit in the same data centre they share it. Sharing is the right default for performance, because either node can then answer a repeat query without touching the database. It also means two processes write into one keyspace, which is where the bug lived.

Cloudflare's account of the plumbing is specific. A cached entry is keyed on a hash of the query's wire messages with some normalisation, and the value is the result bytes. For that to work, the same response has to be stored as the same bytes no matter which node stored it, and the post is candid that the implementation carried an assumption from the Postgres work: that the bytes written back to the Worker are the bytes worth caching.

The MySQL capability mismatch behind the empty results

MySQL makes that assumption unsafe, and the reason is a negotiation detail in its wire protocol. Capabilities are agreed when a connection is established, and one of them, CLIENT_DEPRECATE_EOF, changes how a result set is terminated: the metadata end-of-file packet disappears and the final packet becomes an OK packet. Server 5.7.5 and later supports the capability, and a client has to ask for the newer behaviour.

The popular Node.js driver mysql2 does not ask. Hyperdrive does, so the Endpoint and the Client are working with different capability sets, and the pooler translates every result set into the shape the Worker's driver expects, inserting end-of-file packets and converting OK packets back. Caching the translated bytes breaks that translation in both directions: a Client that finds the Endpoint's result in Hyperdrive's own encoding sends it to the Worker untranslated, and an Endpoint that reads bytes a Client already translated passes them to a different Client, which translates them a second time and ends up sending an early end-of-file packet or hanging.

The symptom was narrow and the explanation is mechanical. One high-volume customer saw roughly 0.001% of queries return empty results where a non-empty answer was always expected, the problem appeared only on instances with caching enabled, and the investigation had to reach the MySQL protocol documentation before the assumption surfaced.

The fix stores one canonical copy per result

Cloudflare's correction is a single rule about what goes into the cache: always store a canonical copy of the result bytes encoded in Hyperdrive's own capabilities, whichever node produced it. The Client then translates on the way out and the Endpoint reads a format it understands. Once that shipped, the empty-row reports stopped and the client-connection success rate reached the vendor's 99.99% target.

Generalisations from one vendor's bug are cheap, and this one holds up anyway. A shared cache with two writers needs one agreed serialisation, and a translation layer needs to decide which side of the cache it runs on. The same discipline applies to any pooled or cached data path a team operates, including the caches that sit in front of an inference stack.

The smaller bugs that added up to general availability

The post describes the gap between beta and general availability as twenty bug fixes, and the two encoding defects are worth keeping because they show the same class of failure at lower stakes. The startup handshake negotiated utf8, a deprecated alias for utf8mb3 that covers one to three bytes per code point, so emoji written to the database came back broken; the fix was to negotiate utf8mb4.

The second came from a cleanup step. Hyperdrive clears session state between checkouts with COM_RESET_CONNECTION, which returns a connection to the server default rather than the encoding agreed at startup, so a server defaulting to latin1 handed back a latin1 connection and the pooler had to set the encoding again after every reset. Both bugs are the sort that a test suite written against the happy path misses and a customer with unusual data finds.

Reading the 99.99% success rate

Cloudflare reports the figure as its success rate for Client connections, and it matches the 99.99% production availability target the beta set out to validate; it is the vendor's own number, and the post cites no independent measurement. For readers planning a migration, Cloudflare's product page and developer documentation state that Hyperdrive supports any MySQL or Postgres database, including managed services and Postgres-compatible engines, and the documentation lists the supported drivers.

For a team running a regional database behind an application that is read-heavy and globally distributed, the operational case is straightforward. Put one read path through the pooler, measure the cache hit rate on real traffic, and watch the two numbers that this release turned on: the rate of empty or malformed responses, and the connection success rate. Netics runs that kind of measurement work with DevOps pipelines and managed monitoring, and the cache-consistency lesson has a harder-edged sibling in what a misplaced cache endpoint exposes, which is how we read the unauthenticated KV cache server earlier in October.

Sources

Source: Inside Hyperdrive: How we solved a rare Hyperdrive MySQL caching bug — blog.cloudflare.com, Cloudflare engineering post, 14 October 2026, retrieved 2026-10-15 (general availability for Hyperdrive's MySQL support; Hyperdrive as a distributed database connection pooler holding warm SQL connections and caching common queries in the global CDN cache; connection establishment taking a minimum of five network round trips and MySQL avoiding Postgres's per-connection OS process; the beta described as the point where real customer usage validated a 99.99% availability target; twenty bug fixes between beta and general availability; the utf8 handshake alias for utf8mb3 and the move to utf8mb4 that fixed emoji handling; COM_RESET_CONNECTION returning a connection to the server default encoding, with the post's example of a server defaulting to latin1, and the fix of re-setting it after each reset; the highest-volume MySQL customer's roughly 0.001% rate of empty query responses with caching enabled and the investigation through telemetry, increased trace rate and the MySQL client-server protocol documentation; the Client and Endpoint topology with the CDN cache local to each data centre and shared when both nodes run in the same data centre; cache entries keyed on a hash of the query's wire messages with result bytes as the value; MySQL server 5.7.5 and later supporting CLIENT_DEPRECATE_EOF, with the OK-packet behaviour used only when the client negotiates it; mysql2 for Node.js not supporting CLIENT_DEPRECATE_EOF and Hyperdrive rewriting result sets to match the Worker driver's capabilities; the assumption carried from Postgres that the bytes written back to the Worker can be cached, while the Client writes translated bytes and the Endpoint works with Hyperdrive's capabilities; the two failure paths, a Client returning the Endpoint's untranslated bytes to a Worker and a second Client re-translating bytes another Client had already translated, ending in an early EOF or a hang; the fix of always writing a canonical copy encoded in Hyperdrive's capabilities regardless of which node stored it; the empty-row problem disappearing and the client connection success rate reaching 99.99%).

Source: Cloudflare Hyperdrive product page and Hyperdrive developer documentation — cloudflare.com/products/hyperdrive and developers.cloudflare.com/hyperdrive, retrieved 2026-10-15 (connection pooling providing 3x faster queries from globally distributed Workers and optional caching for 100x speed and scale on repeated queries; sub-5ms cached query results; compatibility with PostgreSQL, MySQL and popular ORMs through a connection-string swap; caching at more than 330 locations; support for any Postgres or MySQL database including those hosted on AWS, Google Cloud, Azure, Neon and PlanetScale plus Postgres-compatible databases such as CockroachDB and Timescale; mysql2 and mysql among the documented MySQL libraries).

Source: Build global MySQL apps using Cloudflare Workers and Hyperdrive — blog.cloudflare.com, Cloudflare post of 8 April 2025, retrieved 2026-10-15 (the original announcement of MySQL support in Hyperdrive and Workers, with native MySQL drivers and connections to MySQL databases wherever they are hosted).

Source: Cloudflare's Hyperdrive MySQL post of 14 October 2026, its product page, its developer documentation and its April 2025 beta announcement — the figures and mechanism described above, retrieved 2026-10-15. Images are two official Cloudflare figures from the post, plus two Netics editorial diagrams.