Connect to a MySQL database with Cloudflare Workers

In this tutorial, you will learn how to create a Cloudflare Workers application and connect it to a MySQL database using TCP Sockets and Hyperdrive. The Workers application you create in this tutorial will interact with a product database inside of MySQL.

To continue:

1. Sign up for a Cloudflare account ↗ if you have not already.
2. Install npm ↗.
3. Install Node.js ↗. Use a Node version manager like Volta ↗ or nvm ↗ to avoid permission issues and change Node.js versions. Wrangler requires a Node version of 16.17.0 or later.
4. Make sure you have access to a MySQL database.

First, use the create-cloudflare CLI ↗ to create a new Worker application. To do this, open a terminal window and run the following command:

npm create cloudflare@latest -- mysql-tutorial

yarn create cloudflare mysql-tutorial

pnpm create cloudflare@latest mysql-tutorial

This will prompt you to install the create-cloudflare ↗ package and lead you through a setup wizard.

For setup, select the following options:

• For What would you like to start with?, choose Hello World Starter.
• For Which template would you like to use?, choose Worker only.
• For Which language do you want to use?, choose TypeScript.
• For Do you want to use git for version control?, choose Yes.
• For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

If you choose to deploy, you will be asked to authenticate (if not logged in already), and your project will be deployed. If you deploy, you can still modify your Worker code and deploy again at the end of this tutorial.

Now, move into the newly created directory:

cd mysql-tutorial

Node.js compatibility is required for database drivers, including 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"
}

compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"

Create a Hyperdrive configuration using the connection string for your MySQL database.

npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

This command outputs the Hyperdrive configuration id that will be used for your Hyperdrive binding. Set up your binding by specifying the id in the Wrangler file.

{
  "name": "hyperdrive-example",
  "main": "src/index.ts",
  "compatibility_date": "2024-08-21",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
    }
  ]
}

name = "hyperdrive-example"
main = "src/index.ts"
compatibility_date = "2024-08-21"
compatibility_flags = ["nodejs_compat"]

# Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"

Install the mysql2 ↗ driver:

npm i mysql2@>3.13.0

yarn add mysql2@>3.13.0

pnpm add mysql2@>3.13.0

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

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id-here>"
    }
  ]
}

# required for database drivers to function
compatibility_flags = ["nodejs_compat"]
compatibility_date = "2024-09-23"

[[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 connection using the mysql2 driver with the Hyperdrive credentials (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,

      // Required to enable mysql2 compatibility for Workers
      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 Response.json({ results, fields });
    } catch (e) {
      console.error(e);
    }
  },
} satisfies ExportedHandler<Env>;

Run the following command to deploy your Worker:

npx wrangler deploy

Your application is now live and accessible at <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

To build more with databases and Workers, refer to Tutorials and explore the Databases documentation.

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on Discord ↗ to connect with fellow developers and the Cloudflare team.