|
| 1 | +--- |
| 2 | +type: overview |
| 3 | +pcx_content_type: content |
| 4 | +title: Connect to MySQL |
| 5 | +hideChildren: false |
| 6 | +sidebar: |
| 7 | + order: 2 |
| 8 | + group: |
| 9 | + hideIndex: false |
| 10 | +--- |
| 11 | + |
| 12 | +import { TabItem, Tabs, Render, WranglerConfig } from "~/components"; |
| 13 | + |
| 14 | +Hyperdrive supports MySQL and MySQL-compatible databases, [popular drivers](#supported-drivers) and Object Relational Mapper (ORM) libraries that use those drivers. |
| 15 | + |
| 16 | +## Create a Hyperdrive |
| 17 | + |
| 18 | +:::note |
| 19 | + |
| 20 | +New to Hyperdrive? Refer to the [Get started guide](/hyperdrive/get-started/) to learn how to set up your first Hyperdrive. |
| 21 | + |
| 22 | +::: |
| 23 | + |
| 24 | +To create a Hyperdrive that connects to an existing MySQL database, use the [wrangler](/workers/wrangler/install-and-update/) CLI or the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive). |
| 25 | + |
| 26 | +When using wrangler, replace the placeholder value provided to `--connection-string` with the connection string for your database: |
| 27 | + |
| 28 | +```sh |
| 29 | +# wrangler v3.11 and above required |
| 30 | +npx wrangler hyperdrive create my-first-hyperdrive --connection-string= "mysql://user:[email protected]:3306/databasenamehere" |
| 31 | +``` |
| 32 | + |
| 33 | +The command above will output the ID of your Hyperdrive, which you will need to set in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project: |
| 34 | + |
| 35 | +<WranglerConfig> |
| 36 | + |
| 37 | +```toml |
| 38 | +# required for database drivers to function |
| 39 | +compatibility_flags = ["nodejs_compat"] |
| 40 | +compatibility_date = "2024-09-23" |
| 41 | + |
| 42 | +[[hyperdrive]] |
| 43 | +binding = "HYPERDRIVE" |
| 44 | +id = "<your-hyperdrive-id-here>" |
| 45 | +``` |
| 46 | + |
| 47 | +</WranglerConfig> |
| 48 | + |
| 49 | +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](#driver-examples) to learn how to set up a database driver with Hyperdrive. |
| 50 | + |
| 51 | +Refer to the [Examples documentation](/hyperdrive/examples/) for step-by-step guides on how to set up Hyperdrive with several popular database providers. |
| 52 | + |
| 53 | +## Supported drivers |
| 54 | + |
| 55 | +Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/#connect) to support TCP connections to databases. The following table lists the supported database drivers and the minimum version that works with Hyperdrive: |
| 56 | + |
| 57 | +| Driver | Documentation | Minimum Version Required | Notes | |
| 58 | +| ------------------------ | ---------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 59 | +| mysql2 ( **recommended **) | [mysql2 documentation ](https://github.com/sidorares/node-mysql2) | `[email protected]` | Supported in both Workers & Pages. Using the Promise API is recommended. | |
| 60 | +| mysql | [mysql documentation ](https://github.com/mysqljs/mysql) | `[email protected]` | Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date = "2024-09-23"` - refer to [Node.js compatibility ](/workers/runtime-apis/nodejs). Requires wrangler `3.78.7` or later. | |
| 61 | +| Drizzle | [Drizzle documentation ](https://orm.drizzle.team/) | Requires `[email protected]` | | |
| 62 | +| Kysely | [Kysely documentation ](https://kysely.dev/) | Requires `[email protected]` | | |
| 63 | +| Prisma | [Prisma documentation ](https://www.prisma.io/) | Requires `[email protected]` | | |
| 64 | +| TypeORM | [Kysely documentation ](https://typeorm.io/) | Requires `[email protected]` | | |
| 65 | + |
| 66 | +^ _The marked libraries can use either mysql or mysql2 as a dependency._ |
| 67 | + |
| 68 | +Other drivers and ORMs not listed may also be supported: this list is not exhaustive. |
| 69 | + |
| 70 | +### Database drivers and Node.js compatibility |
| 71 | + |
| 72 | +[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including mysql and mysql2, and needs to be configured for your Workers project. |
| 73 | + |
| 74 | +<Render file="nodejs_compat" product="workers" /> |
| 75 | + |
| 76 | +## Supported TLS (SSL) modes |
| 77 | + |
| 78 | +Hyperdrive supports the following MySQL TLS/SSL connection modes when connecting to your origin database: |
| 79 | + |
| 80 | +| Mode | Supported | Details | |
| 81 | +| ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ | |
| 82 | +| `DISABLED` | No | Hyperdrive does not support insecure plain text connections. | |
| 83 | +| `PREFERRED` | No (use `required`) | Hyperdrive will always use TLS. | |
| 84 | +| `REQUIRED` | Yes (default) | TLS is required, and server certificates are validated (based on WebPKI). | |
| 85 | +| `VERIFY_CA` | Not currently supported in beta | Verifies the server's TLS certificate is signed by a root CA on the client. | |
| 86 | +| `VERIFY_IDENTITY` | Not currently supported in beta | Identical to `VERIFY_CA`, but also requires that the database hostname matches the certificate's Common Name (CN). | |
| 87 | + |
| 88 | +:::note |
| 89 | + |
| 90 | +Hyperdrive does not currently support `VERIFY_CA` or `VERIFY_IDENTITY` for MySQL (beta). |
| 91 | + |
| 92 | +::: |
| 93 | + |
| 94 | +## Driver examples |
| 95 | + |
| 96 | +The following examples show you how to: |
| 97 | + |
| 98 | +1. Create a database client with a database driver. |
| 99 | +2. Pass the Hyperdrive connection string and connect to the database. |
| 100 | +3. Query your database via Hyperdrive. |
| 101 | + |
| 102 | +### `mysql2` |
| 103 | + |
| 104 | +The following Workers code shows you how to use [mysql2](https://github.com/sidorares/node-mysql2) with Hyperdrive using the Promise API. |
| 105 | + |
| 106 | +<Render file="use-mysql2-to-make-query" product="hyperdrive" /> |
| 107 | + |
| 108 | +### `mysql` |
| 109 | + |
| 110 | +Install the `mysql` driver: |
| 111 | + |
| 112 | +```sh |
| 113 | +npm install mysql |
| 114 | +``` |
| 115 | + |
| 116 | +**Ensure you have `compatibility_flags` and `compatibility_date` set in your [Wrangler configuration file](/workers/wrangler/configuration/)** as shown below: |
| 117 | + |
| 118 | +<Render file="nodejs-compat-wrangler-toml" product="workers" /> |
| 119 | + |
| 120 | +Create a new connection and pass the Hyperdrive parameters: |
| 121 | + |
| 122 | +```ts |
| 123 | +import { createConnection } from "mysql"; |
| 124 | + |
| 125 | +export interface Env { |
| 126 | + HYPERDRIVE: Hyperdrive; |
| 127 | +} |
| 128 | + |
| 129 | +export default { |
| 130 | + async fetch(request, env, ctx): Promise<Response> { |
| 131 | + const result = await new Promise<any>((resolve) => { |
| 132 | + const connection = createConnection({ |
| 133 | + host: env.HYPERDRIVE.host, |
| 134 | + user: env.HYPERDRIVE.user, |
| 135 | + password: env.HYPERDRIVE.password, |
| 136 | + database: env.HYPERDRIVE.database, |
| 137 | + port: env.HYPERDRIVE.port, |
| 138 | + }); |
| 139 | + |
| 140 | + connection.connect((error: { message: string }) => { |
| 141 | + if (error) { |
| 142 | + throw new Error(error.message); |
| 143 | + } |
| 144 | + |
| 145 | + connection.query("SHOW tables;", [], (error, rows, fields) => { |
| 146 | + connection.end(); |
| 147 | + |
| 148 | + resolve({ fields, rows }); |
| 149 | + }); |
| 150 | + }); |
| 151 | + }); |
| 152 | + |
| 153 | + return new Response(JSON.stringify(result), { |
| 154 | + headers: { |
| 155 | + "Content-Type": "application/json", |
| 156 | + }, |
| 157 | + }); |
| 158 | + }, |
| 159 | +} satisfies ExportedHandler<Env>; |
| 160 | +``` |
| 161 | + |
| 162 | +## Next steps |
| 163 | + |
| 164 | +- Refer to the list of [supported database integrations](/workers/databases/connecting-to-databases/) to understand other ways to connect to existing databases. |
| 165 | +- Learn more about how to use the [Socket API](/workers/runtime-apis/tcp-sockets) in a Worker. |
| 166 | +- Understand the [protocols supported by Workers](/workers/reference/protocols/). |
0 commit comments