Skip to content
Cloudflare Docs

Connect to MySQL

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

Create a Hyperdrive

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:

Terminal window
# 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:

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23",
  "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.

Supported drivers

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:

DriverDocumentationMinimum Version RequiredNotes
mysql2 (recommended)mysql2 documentation ↗mysql2@3.13.0Supported in both Workers & Pages. Using the Promise API is recommended.
mysqlmysql documentation ↗mysql@2.18.0Requires compatibility_flags = ["nodejs_compat"] and compatibility_date = "2024-09-23" - refer to Node.js compatibility. Requires wrangler 3.78.7 or later.
DrizzleDrizzle documentation ↗Requires mysql2@3.13.0
KyselyKysely documentation ↗Requires mysql2@3.13.0

^ 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.

Database drivers and Node.js compatibility

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"
  ],
  "compatibility_date": "2024-09-23"
}

Supported TLS (SSL) modes

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

ModeSupportedDetails
DISABLEDNoHyperdrive does not support insecure plain text connections.
PREFERREDNo (use required)Hyperdrive will always use TLS.
REQUIREDYes (default)TLS is required, and server certificates are validated (based on WebPKI).
VERIFY_CANot currently supported in betaVerifies the server's TLS certificate is signed by a root CA on the client.
VERIFY_IDENTITYNot currently supported in betaIdentical to VERIFY_CA, but also requires that the database hostname matches the certificate's Common Name (CN).

Driver examples

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.

mysql2

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

Install the mysql2 ↗ driver:

Terminal window
# mysql2 v3.13.0 or later is required
npm install mysql2

Create a new connection instance and pass the Hyperdrive parameters:

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


export interface Env {
  // If you set another name in the Wrangler config file as the value for 'binding',
  // replace "HYPERDRIVE" with the variable name you defined.
  HYPERDRIVE: Hyperdrive;
}


export default {
  async fetch(request, env, ctx): Promise<Response> {
    // Create a connection using the mysql2 driver (or any support driver, ORM or query builder)
    // with the Hyperdrive credentials. These credentials are only accessible from your Worker.
    const connection = await createConnection({
      host: env.HYPERDRIVE.host,
      user: env.HYPERDRIVE.user,
      password: env.HYPERDRIVE.password,
      database: env.HYPERDRIVE.database,
      port: env.HYPERDRIVE.port,


      // The following line is needed for mysql2 compatibility with Workers
      // mysql2 uses eval() to optimize result parsing for rows with > 100 columns
      // Configure mysql2 to use static parsing instead of eval() parsing with disableEval
      disableEval: true,
    });


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


      // Clean up the client after the response is returned, before the Worker is killed
      ctx.waitUntil(connection.end());


      // Return result rows as JSON
      return new Response(JSON.stringify({ results, fields }), {
        headers: {
          "Content-Type": "application/json",
          "Access-Control-Allow-Origin": "*",
        },
      });
    } catch (e) {
      console.error(e);
      return Response.json(
        { error: e instanceof Error ? e.message : e },
        { status: 500 },
      );
    }
  },
} satisfies ExportedHandler<Env>;

mysql

Install the mysql driver:

Terminal window
npm install mysql

Ensure you have compatibility_flags and compatibility_date set in your Wrangler configuration file as shown below:

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23"
}

Create a new connection and pass the Hyperdrive parameters:

import { createConnection } from "mysql";


export interface Env {
  HYPERDRIVE: Hyperdrive;
}


export default {
  async fetch(request, env, ctx): Promise<Response> {
    const result = await new Promise<any>((resolve) => {
      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);
        }


        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>;

Identify connections from Hyperdrive

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.

Next steps