Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

MySQL に接続する

最終更新 Markdown で表示Agent セットアップ

Hyperdrive は、MySQL および MySQL 互換データベース、主要なドライバー、およびそれらのドライバーを使う ORM(オブジェクトリレーショナルマッパー)ライブラリに対応しています。

Hyperdrive を作成する

既存の MySQL データベースに接続する Hyperdrive を作成するには、Wrangler CLI または Cloudflare ダッシュボード を使います。

Wrangler を使うときは、--connection-string に渡すプレースホルダーを、自分のデータベースの接続文字列に置き換えます。

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

上記のコマンドは Hyperdrive の ID を出力します。Workers プロジェクトの Wrangler 設定ファイル にこの ID を設定します。

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

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

これで Hyperdrive は、Worker 内で動的な接続文字列を生成します。既存のデータベースドライバーにその文字列を渡せます。ドライバーの設定方法は ドライバーの例 を参照してください。

主要なデータベースプロバイダーで Hyperdrive を設定する手順は、設定例のドキュメント を参照してください。

対応ドライバー

Hyperdrive は、Workers の TCP ソケット対応 を使い、データベースへの TCP 接続をサポートします。次の表は、対応するデータベースドライバーと、Hyperdrive で動作する最小バージョンです。

ドライバー ドキュメント 必要な最小バージョン 備考
mysql2 (推奨) mysql2 のドキュメント mysql2@3.13.0 Workers と Pages の両方で使えます。Promise API の利用を推奨します。
mysql mysql のドキュメント mysql@2.18.0 compatibility_flags = ["nodejs_compat"]compatibility_date = "2024-09-23" が必要です。Node.js compatibility を参照してください。wrangler 3.78.7 以降が必要です。
Drizzle Drizzle のドキュメント mysql2@3.13.0 が必要
Kysely Kysely のドキュメント mysql2@3.13.0 が必要

^ 印の付いたライブラリは、依存関係として mysql または mysql2 のいずれかを使えます。

掲載していない他のドライバーや ORM も使える場合があります。この一覧は網羅的ではありません。

データベースドライバーと Node.js compatibility

mysql や mysql2 を含むデータベースドライバーには Node.js compatibility が必要です。Workers プロジェクトで設定してください。

互換性日付が 2026-08-04 以降の場合、Workers と Pages プロジェクトでは nodejs_compatnodejs_compat_v2 がデフォルトで有効になります。組み込みのランタイム API とポリフィルは、追加の設定なしで使えます。これらの互換性日付では、これらのフラグは使われません。既存プロジェクトは、互換性日付を更新するときにフラグを削除する必要はありません。

互換性日付が 2026-08-04 より前の場合は、オプトインするために Wrangler 設定ファイルnodejs_compat 互換性フラグ を追加します。

{
	"compatibility_flags": [
		"nodejs_compat"
	]
}
compatibility_flags = [ "nodejs_compat" ]

互換性日付が 2026-08-04 以降で Node.js 互換 を完全にオフにするには、有効化フラグがあれば削除します。次に no_nodejs_compatno_nodejs_compat_v2 の両方を追加します。設定例は Node.js 互換性フラグ を参照してください。

対応する TLS(SSL)モード

オリジンデータベースへの接続時、Hyperdrive は次の MySQL TLS/SSL 接続モードに対応しています。

モード 対応 詳細
DISABLED いいえ Hyperdrive は、安全でない平文接続に対応していません。
PREFERRED いいえ(REQUIRED を使います) Hyperdrive は常に TLS を使います。
REQUIRED はい(デフォルト) TLS が必須です。サーバー証明書は(WebPKI に基づいて)検証されます。
VERIFY_CA はい サーバーの TLS 証明書が、クライアント上のルート CA によって署名されていることを検証します。
VERIFY_IDENTITY はい VERIFY_CA の確認に加え、データベースのホスト名が、証明書の Subject Alternative Name(SAN)または Common Name(CN)と一致することを求めます。

Hyperdrive で VERIFY_CA または VERIFY_IDENTITY の TLS(SSL)モードを設定する方法は、SSL/TLS 証明書 のドキュメントを参照してください。

ドライバーの例

次の例では、次の手順を示します。

  1. データベースドライバーでデータベースクライアントを作成します。
  2. Hyperdrive の接続文字列を渡し、データベースに接続します。
  3. Hyperdrive 経由でデータベースにクエリします。

mysql2

次の Workers コードは、Promise API を使って mysql2 を Hyperdrive と組み合わせる方法です。

mysql2 ドライバーをインストールします。

npm i mysql2@>3.13.0

wrangler.jsonc に、必要な Node.js 互換フラグと Hyperdrive バインディングを追加します。

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

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

Hyperdrive のパラメーターを渡して、新しい connection インスタンスを作成します。

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

mysql

次の Workers コードは、mysql を Hyperdrive と組み合わせる方法です。

mysql ドライバーをインストールします。

npm i mysql

必要な Node.js 互換性フラグと Hyperdrive バインディングを wrangler.jsonc ファイルに追加します。

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

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

新しい接続を作成し、Hyperdrive のパラメーターを渡します。

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

Hyperdrive からの接続を識別する

MySQL データベースサーバーへの、Hyperdrive からのアクティブな接続を識別するには、次を使います。

  • Hyperdrive からデータベースへの接続は、performance_schema.threads テーブルの PROGRAM_NAME 列に Cloudflare Hyperdrive と表示されます。
  • SELECT DISTINCT USER, HOST, PROGRAM_NAME FROM performance_schema.threads WHERE PROGRAM_NAME = 'Cloudflare Hyperdrive' を実行すると、Hyperdrive が現在データベースへの接続を開いているかどうかを確認できます。

次のステップ

役に立ちましたか?