Hyperdrive は、MySQL および MySQL 互換データベース、主要なドライバー、およびそれらのドライバーを使う ORM(オブジェクトリレーショナルマッパー)ライブラリに対応しています。
既存の 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:[email protected]: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 のドキュメント ↗ | [email protected] |
Workers と Pages の両方で使えます。Promise API の利用を推奨します。 |
| mysql | mysql のドキュメント ↗ | [email protected] |
compatibility_flags = ["nodejs_compat"] と compatibility_date = "2024-09-23" が必要です。Node.js compatibility を参照してください。wrangler 3.78.7 以降が必要です。 |
| Drizzle | Drizzle のドキュメント ↗ | [email protected] が必要 |
|
| Kysely | Kysely のドキュメント ↗ | [email protected] が必要 |
^ 印の付いたライブラリは、依存関係として mysql または mysql2 のいずれかを使えます。
掲載していない他のドライバーや ORM も使える場合があります。この一覧は網羅的ではありません。
mysql や mysql2 を含むデータベースドライバーには Node.js compatibility が必要です。Workers プロジェクトで設定してください。
互換性日付が 2026-08-04 以降の場合、Workers と Pages プロジェクトでは nodejs_compat と nodejs_compat_v2 がデフォルトで有効になります。組み込みのランタイム API とポリフィルは、追加の設定なしで使えます。これらの互換性日付では、これらのフラグは使われません。既存プロジェクトは、互換性日付を更新するときにフラグを削除する必要はありません。
互換性日付が 2026-08-04 より前の場合は、オプトインするために Wrangler 設定ファイル に nodejs_compat 互換性フラグ を追加します。
{
"compatibility_flags": [
"nodejs_compat"
]
}compatibility_flags = [ "nodejs_compat" ]互換性日付が 2026-08-04 以降で Node.js 互換 を完全にオフにするには、有効化フラグがあれば削除します。次に no_nodejs_compat と no_nodejs_compat_v2 の両方を追加します。設定例は Node.js 互換性フラグ を参照してください。
オリジンデータベースへの接続時、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 証明書 のドキュメントを参照してください。
次の例では、次の手順を示します。
- データベースドライバーでデータベースクライアントを作成します。
- Hyperdrive の接続文字列を渡し、データベースに接続します。
- Hyperdrive 経由でデータベースにクエリします。
次の Workers コードは、Promise API を使って mysql2 ↗ を Hyperdrive と組み合わせる方法です。
mysql2 ↗ ドライバーをインストールします。
npm i mysql2@>3.13.0yarn add mysql2@>3.13.0pnpm add mysql2@>3.13.0bun add mysql2@>3.13.0wrangler.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>;次の Workers コードは、mysql ↗ を Hyperdrive と組み合わせる方法です。
mysql ↗ ドライバーをインストールします。
npm i mysqlyarn add mysqlpnpm add mysqlbun add 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>;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 が現在データベースへの接続を開いているかどうかを確認できます。
- 既存のデータベースへの他の接続方法は、対応するデータベース連携 の一覧を参照してください。
- Worker での Socket API の使い方を確認します。
- Workers が対応するプロトコル を確認します。