From a514556e22f3c8e85804bfe8a4d4ee8dcaa15293 Mon Sep 17 00:00:00 2001 From: Mini256 Date: Thu, 6 Mar 2025 11:08:09 +0800 Subject: [PATCH 1/3] feat: add mysql2 on cloudflare docs --- .../documentation/connect-on-cloudflare.mdx | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 website/docs/documentation/connect-on-cloudflare.mdx diff --git a/website/docs/documentation/connect-on-cloudflare.mdx b/website/docs/documentation/connect-on-cloudflare.mdx new file mode 100644 index 0000000000..4911718055 --- /dev/null +++ b/website/docs/documentation/connect-on-cloudflare.mdx @@ -0,0 +1,79 @@ +# Using MySQL2 on Cloudflare Workers + +This document is a step-by-step tutorial on how to use `node-mysql2` on Cloudflare Workers. + +## Prerequisites + +Before you try the steps in this document, you need to prepare the following things: + +- A [Cloudflare Workers](https://dash.cloudflare.com/login) account. +- [Wrangler](https://developers.cloudflare.com/workers/wrangler/) installed. + +If you haven't created a Cloudflare Worker project yet, please refer to [Get Started Guide](https://developers.cloudflare.com/workers/get-started/guide/) to create one. + + +## Step 1: Configure `wrangler.jsonc` file + +Because of the differences between the Cloudflare Workers runtime and the Node.js runtime, you can't use MySQL2 directly on the worker, but you can enable compatibility mode through configuration: + +```json +{ + "$schema": "node_modules/wrangler/config-schema.json", + "name": "mysql2-cloudflare", + "main": "src/index.ts", + // highlight-start + "compatibility_date": "2025-02-24", + // highlight-end + "observability": { + "enabled": true + }, + // highlight-start + "compatibility_flags": [ + "nodejs_compat" + ] + // highlight-end +} +``` + +## Step 2: Disable code generation-based parser + +MySQL2 uses code generation based parser for performance by default, but this is restricted on Cloudflare Workers. You may encounter the errors like: + +``` +Code generation from strings disallowed for this context +``` + +To make it work, you can disable the code generation-based parser by pass the `disableEval=true` parameter when creating a connection. Here are an example: + +```ts +import { createConnection } from 'mysql2/promise'; + +export default { + async fetch(request, env, ctx): Promise { + const conn = await createConnection({ + host: "", + port: 3306, + user: "", + password: "", + // highlight-start + disableEval: true, + // highlight-end + database: "" + }) + + const [results] = await conn.query("SHOW TABLES;"); + + return new Response(JSON.stringify(results)); + }, +} satisfies ExportedHandler; +``` + +:::tip +For some managed MySQL / MySQL-compatible cloud databases (e.g., TiDB Serverless, Planetscale), connections are usually required to use SSL. It is recommended to use the Cloudflare managed connection pool [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) to connect. +::: + +## Step 3: Test locally + +``` +wrangler dev +``` From f9ef5bdc89c806ebb90b707d1635eb840e831a63 Mon Sep 17 00:00:00 2001 From: Mini256 Date: Thu, 6 Mar 2025 11:27:13 +0800 Subject: [PATCH 2/3] lint --- .../documentation/connect-on-cloudflare.mdx | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/website/docs/documentation/connect-on-cloudflare.mdx b/website/docs/documentation/connect-on-cloudflare.mdx index 4911718055..34328ea372 100644 --- a/website/docs/documentation/connect-on-cloudflare.mdx +++ b/website/docs/documentation/connect-on-cloudflare.mdx @@ -11,7 +11,6 @@ Before you try the steps in this document, you need to prepare the following thi If you haven't created a Cloudflare Worker project yet, please refer to [Get Started Guide](https://developers.cloudflare.com/workers/get-started/guide/) to create one. - ## Step 1: Configure `wrangler.jsonc` file Because of the differences between the Cloudflare Workers runtime and the Node.js runtime, you can't use MySQL2 directly on the worker, but you can enable compatibility mode through configuration: @@ -28,9 +27,7 @@ Because of the differences between the Cloudflare Workers runtime and the Node.j "enabled": true }, // highlight-start - "compatibility_flags": [ - "nodejs_compat" - ] + "compatibility_flags": ["nodejs_compat"] // highlight-end } ``` @@ -51,17 +48,17 @@ import { createConnection } from 'mysql2/promise'; export default { async fetch(request, env, ctx): Promise { const conn = await createConnection({ - host: "", + host: '', port: 3306, - user: "", - password: "", + user: '', + password: '', // highlight-start disableEval: true, // highlight-end - database: "" - }) + database: '', + }); - const [results] = await conn.query("SHOW TABLES;"); + const [results] = await conn.query('SHOW TABLES;'); return new Response(JSON.stringify(results)); }, From d060077dd1da32bb142ec4ad902e9ab0f3680917 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Weslley=20Ara=C3=BAjo?= <46850407+wellwelwel@users.noreply.github.com> Date: Thu, 6 Mar 2025 01:49:45 -0300 Subject: [PATCH 3/3] Update website/docs/documentation/connect-on-cloudflare.mdx --- .../documentation/connect-on-cloudflare.mdx | 80 ++++++++++--------- 1 file changed, 41 insertions(+), 39 deletions(-) diff --git a/website/docs/documentation/connect-on-cloudflare.mdx b/website/docs/documentation/connect-on-cloudflare.mdx index 34328ea372..0b640e8b39 100644 --- a/website/docs/documentation/connect-on-cloudflare.mdx +++ b/website/docs/documentation/connect-on-cloudflare.mdx @@ -1,61 +1,69 @@ -# Using MySQL2 on Cloudflare Workers - -This document is a step-by-step tutorial on how to use `node-mysql2` on Cloudflare Workers. +import { History } from '@site/src/components/History'; + +# Cloudflare Workers + + + Support for non-eval parsers by using{' '} + disableEval option. + , + ], + }, + ]} +/> ## Prerequisites -Before you try the steps in this document, you need to prepare the following things: - -- A [Cloudflare Workers](https://dash.cloudflare.com/login) account. +- A [Cloudflare](https://dash.cloudflare.com/sign-up) account. - [Wrangler](https://developers.cloudflare.com/workers/wrangler/) installed. +- **MySQL2** version `3.13.0` or higher. + +To learn how to create a **Cloudflare Worker** project, please refer to [**Cloudflare Workers Documentation**](https://developers.cloudflare.com/workers/get-started/guide/). -If you haven't created a Cloudflare Worker project yet, please refer to [Get Started Guide](https://developers.cloudflare.com/workers/get-started/guide/) to create one. +## Setup -## Step 1: Configure `wrangler.jsonc` file +### Wrangler -Because of the differences between the Cloudflare Workers runtime and the Node.js runtime, you can't use MySQL2 directly on the worker, but you can enable compatibility mode through configuration: +**MySQL2** relies on **Node.js** modules, such as `net`, `events`, `stream`, `tls`, etc. You can enable **Node.js** compatibility for **Cloudflare Workers** by using the `"nodejs_compat"` flag through the `wrangler.jsonc` file: ```json { - "$schema": "node_modules/wrangler/config-schema.json", - "name": "mysql2-cloudflare", - "main": "src/index.ts", - // highlight-start - "compatibility_date": "2025-02-24", - // highlight-end - "observability": { - "enabled": true - }, - // highlight-start "compatibility_flags": ["nodejs_compat"] - // highlight-end } ``` -## Step 2: Disable code generation-based parser +:::important +The minimum compatibility date is `2025-02-24`, for example: -MySQL2 uses code generation based parser for performance by default, but this is restricted on Cloudflare Workers. You may encounter the errors like: - -``` -Code generation from strings disallowed for this context +```json +{ + "compatibility_date": "2025-02-24", + "compatibility_flags": ["nodejs_compat"] +} ``` -To make it work, you can disable the code generation-based parser by pass the `disableEval=true` parameter when creating a connection. Here are an example: +::: + +### MySQL2 connection + +**MySQL2** uses a code generation-based parser for performance by default, but since **Cloudflare Workers** don't offer support for evaluations, you can disable it by using the `disableEval` option: ```ts import { createConnection } from 'mysql2/promise'; export default { - async fetch(request, env, ctx): Promise { + async fetch(): Promise { const conn = await createConnection({ - host: '', - port: 3306, - user: '', - password: '', + host: 'localhost', + user: 'root', + database: 'test', // highlight-start disableEval: true, // highlight-end - database: '', }); const [results] = await conn.query('SHOW TABLES;'); @@ -66,11 +74,5 @@ export default { ``` :::tip -For some managed MySQL / MySQL-compatible cloud databases (e.g., TiDB Serverless, Planetscale), connections are usually required to use SSL. It is recommended to use the Cloudflare managed connection pool [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) to connect. +For required **SSL** connections, it is recommended to use the [**Cloudflare Hyperdrive**](https://developers.cloudflare.com/hyperdrive/) connection pool. ::: - -## Step 3: Test locally - -``` -wrangler dev -```