Cloudflare Hyperdrive MySQL Support Reaches GA After Fixing Rare Caching Bug

Cloudflare has announced that Hyperdrive support for MySQL is now generally available (GA). Initially launched in beta last year, the service has undergone significant reliability improvements to match its existing Postgres support. The transition from beta to GA involved approximately 20 bug fixes, addressing issues ranging from character encoding to complex protocol handling.

The Rare Caching Bug

During the beta phase, a high-volume customer reported a rare issue where query responses were empty, occurring in about 0.001% of cases. Investigation revealed the bug was tied to Hyperdrive's caching mechanism when the Client and Endpoint nodes shared a CDN cache in the same data center. The root cause was a mismatch in MySQL protocol capabilities between the two nodes.

Hyperdrive acts as a server to the Worker and a client to the origin database. It negotiates specific capabilities, such as CLIENT_DEPRECATE_EOF, which changes how result sets are terminated. However, some popular client libraries like mysql2 do not support this capability. When the Client node cached bytes translated for the Worker's capabilities, but the Endpoint node (which uses Hyperdrive's fixed capabilities) read those bytes, the protocol desync resulted in empty responses or hangs.

Resolution and Availability

The fix ensures that Hyperdrive always writes a canonical version of query result bytes to the cache, encoded using Hyperdrive's own capabilities, regardless of which node stored them. This change eliminated the empty row problem and brought the success rate for Client connections to 99.99%.

Users can now connect to existing MySQL-compatible databases or new PlanetScale databases using the wrangler CLI or the Cloudflare dashboard. The command to create a Hyperdrive instance is:

npx wrangler hyperdrive create HYPERDRIVE_NAME --connection-string="mysql://user:[email protected]:3306/dbname"