はじめに

Hyperdrive は、既存のデータベースへのアクセスを Cloudflare Workers から高速化します。単一リージョンのデータベースでも、グローバルに分散しているように感じられます。

Cloudflare のネットワーク内でデータベースへの接続プールを維持することで、クエリを送る前に発生する 7 回のラウンドトリップを削減します。内訳は TCP ハンドシェイク（1 回）、TLS ネゴシエーション（3 回）、データベース認証（3 回）です。

Hyperdrive はデータベースへの読み取りクエリと書き込みクエリを区別し、よく使われる読み取りクエリをキャッシュします。パフォーマンスが向上し、オリジンデータベースの負荷も下がります。

このガイドでは、次の内容を扱います。

• 最初の Hyperdrive 設定を作成する。
• Cloudflare Worker を作成し、Hyperdrive 設定にバインドする。
• Worker から公開データベースへ接続する。

始める前に、次を完了してください。

1. まだの場合は Cloudflare アカウント ↗ に登録します。
2. Node.js ↗ をインストールします。権限の問題を避け、Node.js のバージョンを切り替えられるよう、nvm ↗ や Volta ↗ などの Node バージョンマネージャーを使います。Wrangler には Node 16.17.0 以降が必要です。
3. 公開アクセス可能な PostgreSQL または MySQL（あるいは互換）データベースを用意します。データベースがプライベートネットワークにある場合は、Workers VPC でプライベートデータベースに接続する を参照してください。

Hyperdrive バインディングを作成する前に、次のコマンドで Cloudflare アカウントにログインします。

npx wrangler login

Cloudflare ダッシュボードへのログインを求める Web ページが開きます。ログイン後、Wrangler が Cloudflare アカウントを変更してよいか確認されます。下にスクロールし、Allow を選択して続行します。

次のコマンドで、hyperdrive-tutorial という名前の新しいプロジェクトを作成します。

npm create cloudflare@latest -- hyperdrive-tutorial

yarn create cloudflare hyperdrive-tutorial

pnpm create cloudflare@latest hyperdrive-tutorial

セットアップでは、次のオプションを選びます。

• What would you like to start with? では、Hello World example を選びます。
• Which template would you like to use? では、Worker only を選びます。
• Which language do you want to use? では、TypeScript を選びます。
• Do you want to use git for version control? では、Yes を選びます。
• Do you want to deploy your application? では、No を選びます（デプロイ前にいくつか変更します）。

これで新しい hyperdrive-tutorial ディレクトリが作成されます。ディレクトリの内容は次のとおりです。

• src/index.ts にある "Hello World" Worker。
• wrangler.jsonc 設定ファイル。hyperdrive-tutorial Worker は、このファイルで Hyperdrive に接続します。

データベースドライバーには Node.js 互換 が必要です。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 はデータベースに接続し、データベース接続をグローバルにプールし、Cloudflare のネットワーク経由でデータベースアクセスを高速化します。

Worker からのみアクセスできる安全な接続文字列が提供され、Hyperdrive 経由でデータベースに接続できます。 そのため、既存のドライバーや ORM ライブラリに、大きなコード変更なしで Hyperdrive の接続文字列を使えます。

最初の Hyperdrive データベース設定を作成するには、作成したばかりの Workers プロジェクトのディレクトリに移動します。

cd hyperdrive-tutorial

最初の Hyperdrive を作成するには、次が必要です。

• データベースの IP アドレス（またはホスト名）とポート。
• データベースのユーザー名（例: hyperdrive-demo）。
• そのユーザー名に対応するパスワード。
• Hyperdrive を接続するデータベース名。例: postgres または mysql。

Hyperdrive は、データベースドライバーで一般的な接続文字列形式で、これらのパラメーターの組み合わせを受け取ります。

postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

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

mysql://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

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

成功すると、コマンドは新しい Hyperdrive 設定を出力します。

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<example id: 57b7076f58be42419276f058a8968187>"
		}
	]
}

id フィールドをコピーします。次のステップで、Worker スクリプトから Hyperdrive にアクセスするために使います。

Worker を Hyperdrive 設定に接続するには、Wrangler 設定ファイル にバインディングを作成する必要があります。バインディング を使うと、Worker から Hyperdrive など Cloudflare 開発者プラットフォーム上のリソースにアクセスできます。

Hyperdrive 設定を Worker にバインドするには、Wrangler ファイルの末尾に次を追加します。

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<YOUR_DATABASE_ID>" // the ID associated with the Hyperdrive you just created
		}
	]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>"

具体的には次のとおりです。

• binding（バインディング名）に設定した値（文字列）は、Worker 内でこのデータベースを参照するために使います。このチュートリアルでは、バインディング名を HYPERDRIVE にします。
• バインディングは 有効な JavaScript 変数名 ↗ である必要があります。たとえば binding = "hyperdrive" や binding = "productionDB" は、どちらも有効なバインディング名です。
• バインディングは Worker 内の env.<BINDING_NAME> で使えます。

開発中にローカルデータベースを使いたい場合は、Hyperdrive 設定に localConnectionString を追加し、データベースの接続文字列を指定します。

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<YOUR_DATABASE_ID>", // the ID associated with the Hyperdrive you just created
			"localConnectionString": "<LOCAL_DATABASE_CONNECTION_URI>"
		}
	]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>"
localConnectionString = "<LOCAL_DATABASE_CONNECTION_URI>"

Hyperdrive 設定を作成して Worker にバインドしたら、データベースに対してクエリを実行できます。

# This should install v8.13.0 or later
npm i pg

# This should install v8.13.0 or later
yarn add pg

# This should install v8.13.0 or later
pnpm add pg

# This should install v8.13.0 or later
bun add pg

# This should install v8.13.0 or later
npm i -D @types/pg

# This should install v8.13.0 or later
yarn add -D @types/pg

# This should install v8.13.0 or later
pnpm add -D @types/pg

# This should install v8.13.0 or later
bun add -d @types/pg

# This should install v3.13.0 or later
npm i mysql2

# This should install v3.13.0 or later
yarn add mysql2

# This should install v3.13.0 or later
pnpm add mysql2

# This should install v3.13.0 or later
bun add mysql2

// pg 8.13.0 or later is recommended
import { Client } from "pg";

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a new client on each request. Hyperdrive maintains the underlying
		// database connection pool, so creating a new client is fast.
		const sql = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});

		try {
			// Connect to the database
			await sql.connect();

			// Sample query
			const results = await sql.query(`SELECT * FROM pg_tables`);

			// Return result rows as JSON
			return Response.json(results.rows);
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

// mysql2 v3.13.0 or later is required
import { createConnection } from "mysql2/promise";

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

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,

			// The following line is needed for mysql2 compatibility with Workers
			// mysql2 uses eval() to optimize result parsing for rows with > 100 columns
			// Configure mysql2 to use static parsing instead of eval() parsing with disableEval
			disableEval: true,
		});

		try {
			// Sample query
			const [results, fields] = await connection.query("SHOW tables;");

			// Return result rows as JSON
			return new Response(JSON.stringify({ results, fields }), {
				headers: {
					"Content-Type": "application/json",
					"Access-Control-Allow-Origin": "*",
				},
			});
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;

デプロイ前に、wrangler dev を実行して Worker をローカルでテストできます。Worker コードは手元のマシンで動き、データベースに接続します。

localConnectionString フィールドは、ローカルとリモートのどちらのデータベースでも使え、ローカル実行中の Worker プロジェクトからデータベースへ直接接続できます。必要な場合は SSL/TLS モードを指定します（Postgres は sslmode=require、MySQL は sslMode=REQUIRED）。

ローカル開発でデータベースに接続するには、wrangler.jsonc で localConnectionString を設定します。

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "your-hyperdrive-id",
			"localConnectionString": "postgres://user:password@your-database-host:5432/database",
		},
	],
}

または環境変数を設定します。

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"

その後、ローカル開発を開始します。

npx wrangler dev

Worker をデプロイすると、プロジェクトをインターネットから利用できます。デプロイするには、次を実行します。

npx wrangler deploy
# Outputs: https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev

新しく作成したプロジェクトの URL にアクセスすると、稼働中のデータベースにクエリできます。

たとえば、新しい Worker の URL が hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev の場合、https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ にアクセスすると、データベースへ直接クエリするリクエストが Worker に送られます。

このチュートリアルを完了すると、Hyperdrive 設定と、そのデータベースにアクセスする Worker を作成し、プロジェクトをグローバルにデプロイしたことになります。

• Hyperdrive の仕組み を確認します。
• クエリキャッシュの設定 方法を確認します。
• データベースを Hyperdrive に接続するときの よくある問題のトラブルシューティング を確認します。

機能の要望や不具合を見つけた場合は、Discord の Cloudflare Developers コミュニティ ↗ に参加して、Cloudflare チームへ直接フィードバックを共有してください。