
Cloudflare Workers and Hyperdrive now support MySQL. Workers applications can connect directly to MySQL databases regardless of where they are hosted, using native MySQL drivers, with Hyperdrive free on the Workers free plan.
Why MySQL drivers didn't run on Workers
Workers have been able to open TCP connections for some time, but the popular MySQL drivers depended on Node.js APIs the runtime did not provide. Two workarounds existed: PlanetScale's serverless driver for JavaScript, which relays database messages over HTTP instead of TCP, and a fork of the mysql package that polyfilled the missing Node.js dependencies. Neither was a full answer. One was limited to a single MySQL hosting provider, both required new libraries rather than the drivers production codebases already used, and neither integrated with existing tooling built around mysql and mysql2.

Getting the drivers working
Cloudflare identified net and stream as the APIs both drivers needed. Combined with nodejs_compat, which resolves unused Node.js dependencies via unenv, this was enough for the mysql package to run on Workers.
import { createConnection } from 'mysql';
export default {
async fetch(request, env, ctx): Promise<Response> {
const result = await new Promise<any>((resolve) => {
const connection = createConnection({
host: env.DB_HOST,
user: env.DB_USER,
password: env.DB_PASSWORD,
database: env.DB_NAME,
port: env.DB_PORT
});
connection.connect((error: { message : string }) => {
if(error) {
throw new Error(error.message);
}
connection.query("SHOW tables;", [], (error, rows, fields) => {
connection.end();
resolve({ fields, rows });
});
});
});
return new Response(JSON.stringify(result), {
headers: {
'Content-Type': 'application/json',
},
});
},
} satisfies ExportedHandler<Env>;
mysql2 needed more. It still relied on Node.js timers — support for which landed in the Workers runtime — and on JavaScript eval, which Cloudflare could not securely enable at this time.
The driver uses eval to speed up parsing of results containing large rows with more than 100 columns. A prior effort already existed to run mysql2 on Workers using static parsers for text and binary MySQL data types without eval(), which performs similarly in most scenarios. Version 3.13.0 of mysql2 shipped an option to disable eval() for this purpose:
import { createConnection } from 'mysql2/promise';
export default {
async fetch(request, env, ctx): Promise<Response> {
const connection = await createConnection({
host: env.DB_HOST,
user: env.DB_USER,
password: env.DB_PASSWORD,
database: env.DB_NAME,
port: env.DB_PORT
// The following line is needed for mysql2 to work on Workers (as explained above)
// mysql2 uses eval() to optimize result parsing for rows with > 100 columns
// eval() is not available in Workers due to runtime limitations
// Configure mysql2 to use static parsing with disableEval
disableEval: true
});
const [results, fields] = await connection.query(
'SHOW tables;'
);
return new Response(JSON.stringify({ results, fields }), {
headers: {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*',
},
});
},
} satisfies ExportedHandler<Env>;
What Hyperdrive adds
Drivers alone don't make for a fast application. Database drivers require many roundtrips to establish a connection, and without connection reuse between Worker invocations that setup cost becomes unnecessary latency on every request. Hyperdrive pools connections to the database globally and removes the roundtrips for connection setup; it also caches popular queries to offload the database.

Supporting MySQL required Hyperdrive to parse the MySQL wire protocol, the prerequisite for extracting queries from protocol messages, caching results across Cloudflare locations, relaying messages to a datacenter near the database, and pooling connections close to the origin. MySQL differs from Postgres in ways that required adaptation: authentication plugins vary across providers, and the connection handshake relies on capability flags. The Postgres work served as the starting point, and MySQL support launches with all of Hyperdrive's existing performance improvements in place.
Configuring a MySQL Hyperdrive setup
Hyperdrive configurations can be created for MySQL databases hosted anywhere. Cloudflare has tested MySQL and MariaDB databases from AWS (including AWS Aurora), GCP, Azure, PlanetScale and self-hosted deployments. Configurations are created from the dashboard or the Wrangler CLI:
wrangler hyperdrive create mysql-hyperdrive
--connection-string="mysql://user:[email protected]:3306/defaultdb"
The Wrangler configuration file needs the Hyperdrive binding set to the new configuration's ID, along with Node.js compatibility flags:
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "workers-mysql-template",
"main": "src/index.ts",
"compatibility_date": "2025-03-10",
"observability": {
"enabled": true
},
"compatibility_flags": [
"nodejs_compat"
],
"hyperdrive": [
{
"binding": "HYPERDRIVE",
"id": "<HYPERDRIVE_CONFIG_ID>"
}
]
}
The binding supplies custom connection credentials pointing at the Hyperdrive configuration. Hyperdrive routes all queries and database messages onward to the origin database, using Cloudflare's network to speed up routing.
import { createConnection } from 'mysql2/promise';
export interface Env {
HYPERDRIVE: Hyperdrive;
}
export default {
async fetch(request, env, ctx): Promise<Response> {
// Hyperdrive provides new connection credentials to use with your existing drivers
const connection = await createConnection({
host: env.HYPERDRIVE.host,
user: env.HYPERDRIVE.user,
password: env.HYPERDRIVE.password,
database: env.HYPERDRIVE.database,
port: env.HYPERDRIVE.port,
// Configure mysql2 to use static parsing (as explained above in Part 1)
disableEval: true
});
const [results, fields] = await connection.query(
'SHOW tables;'
);
return new Response(JSON.stringify({ results, fields }), {
headers: {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*',
},
});
},
} satisfies ExportedHandler<Env>;
Migration amounts to swapping the credentials in the JavaScript code for those Hyperdrive provides. Existing ORMs and drivers stay as they are.
Status and next steps
A template is available for starting a MySQL project on Workers with Hyperdrive, alongside the deploy button above.
During the beta, Cloudflare will continue iterating on MySQL support to cover more of the MySQL protocol and MySQL-compatible databases, and will keep expanding Hyperdrive's feature set for full-stack workloads.
Feedback on MySQL support, Hyperdrive and building global applications on Workers is welcome in the #hyperdrive channel of the Developer Discord.



