Connect to MySQL

Hyperdrive supports MySQL and MySQL-compatible databases, popular drivers, and Object Relational Mapper (ORM) libraries that use those drivers.

To create a Hyperdrive that connects to an existing MySQL database, use the Wrangler CLI or the Cloudflare dashboard ↗.

When using Wrangler, replace the placeholder value provided to --connection-string with the connection string for your database:

# wrangler v3.11 and above required
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="mysql://user:password@database.host.example.com:3306/databasenamehere"

The command above will output the ID of your Hyperdrive, which you will need to set in the Wrangler configuration file for your Workers project:

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-07-20",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-07-20"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to Driver examples to learn how to set up a database driver with Hyperdrive.

Refer to the Examples documentation for step-by-step guides on how to set up Hyperdrive with several popular database providers.

Hyperdrive uses Workers TCP socket support to support TCP connections to databases. The following table lists the supported database drivers and the minimum version that works with Hyperdrive:

^ The marked libraries can use either mysql or mysql2 as a dependency.

Other drivers and ORMs not listed may also be supported: this list is not exhaustive.

Node.js compatibility is required for database drivers, including mysql and mysql2, and needs to be configured for your Workers project.

To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the nodejs_compat compatibility flag to your Wrangler configuration file, and set your compatibility date to September 23rd, 2024 or later. This will enable Node.js compatibility for your Workers project.

{
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-07-20"
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-07-20"

Hyperdrive supports the following MySQL TLS/SSL connection modes when connecting to your origin database:

Refer to SSL/TLS certificates documentation for details on how to configure VERIFY_CA or VERIFY_IDENTITY TLS (SSL) modes for Hyperdrive.

The following examples show you how to:

1. Create a database client with a database driver.
2. Pass the Hyperdrive connection string and connect to the database.
3. Query your database via Hyperdrive.

The following Workers code shows you how to use mysql2 ↗ with Hyperdrive using the Promise API.

Install the mysql2 ↗ driver:

								
									
									npm
									 i mysql2@>3.13.0
								
							

								
									
									yarn
									 add mysql2@>3.13.0
								
							

								
									
									pnpm
									 add mysql2@>3.13.0
								
							

								
									
									bun
									 add mysql2@>3.13.0
								
							

Add the required Node.js compatibility flags and Hyperdrive binding to your wrangler.jsonc file:

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-07-20",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-07-20"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

Create a new connection instance and pass the Hyperdrive parameters:

// mysql2 v3.13.0 or later is required
import { createConnection } from "mysql2/promise";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new connection on each request. Hyperdrive maintains the underlying
		// database connection pool, so creating a new connection is fast.
		const connection = await createConnection({
			host: env.HYPERDRIVE.host,
			user: env.HYPERDRIVE.user,
			password: env.HYPERDRIVE.password,
			database: env.HYPERDRIVE.database,
			port: env.HYPERDRIVE.port,

			// Required to enable mysql2 compatibility for Workers
			disableEval: true,
		});

		try {
			// Sample query
			const [results, fields] = await connection.query("SHOW tables;");

			// Return result rows as JSON
			return Response.json({ results, fields });
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

The following Workers code shows you how to use mysql ↗ with Hyperdrive.

Install the mysql ↗ driver:

								
									
									npm
									 i mysql
								
							

								
									
									yarn
									 add mysql
								
							

								
									
									pnpm
									 add mysql
								
							

								
									
									bun
									 add mysql
								
							

Add the required Node.js compatibility flags and Hyperdrive binding to your wrangler.jsonc file:

{
	// required for database drivers to function
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-07-20",
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<your-hyperdrive-id-here>"
		}
	]
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-07-20"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

Create a new connection and pass the Hyperdrive parameters:

import { createConnection } from "mysql";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const result = await new Promise<any>((resolve) => {
			// Create a connection using the mysql driver with the Hyperdrive credentials (only accessible from your Worker).
			const connection = createConnection({
				host: env.HYPERDRIVE.host,
				user: env.HYPERDRIVE.user,
				password: env.HYPERDRIVE.password,
				database: env.HYPERDRIVE.database,
				port: env.HYPERDRIVE.port,
			});

			connection.connect((error: { message: string }) => {
				if (error) {
					throw new Error(error.message);
				}

				// Sample query
				connection.query("SHOW tables;", [], (error, rows, fields) => {
					resolve({ fields, rows });
				});
			});
		});

		// Return result  as JSON
		return new Response(JSON.stringify(result), {
			headers: {
				"Content-Type": "application/json",
			},
		});
	},
} satisfies ExportedHandler<Env>;

To identify active connections to your MySQL database server from Hyperdrive:

• Hyperdrive's connections to your database will show up with Cloudflare Hyperdrive in the PROGRAM_NAME column in the performance_schema.threads table.
• Run SELECT DISTINCT USER, HOST, PROGRAM_NAME FROM performance_schema.threads WHERE PROGRAM_NAME = 'Cloudflare Hyperdrive' to show whether Hyperdrive is currently holding a connection (or connections) open to your database.

• Refer to the list of supported database integrations to understand other ways to connect to existing databases.
• Learn more about how to use the Socket API in a Worker.
• Understand the protocols supported by Workers.