Tunnel でプライベートデータベースに接続する

Hyperdrive は、Cloudflare Tunnel と Cloudflare Access を使い、プライベートデータベースへ安全に接続できます。

データベースがプライベートネットワーク（仮想プライベートクラウド ↗ やオンプレミスネットワークなど）に隔離されている場合、そのネットワークから Cloudflare への安全な接続を有効にする必要があります。

• Cloudflare Tunnel は、安全なトンネル接続を確立するために使います。
• Cloudflare Access は、特定の Hyperdrive 構成だけがトンネルへアクセスできるように制限するために使います。

Cloudflare Worker からオリジンデータベースへのリクエストは、Hyperdrive、Cloudflare Access、cloudflared が確立した Cloudflare Tunnel を経由します。cloudflared は、データベースへ到達できるプライベートネットワーク内で稼働している必要があります。

Cloudflare Tunnel は、プライベートネットワークから Cloudflare へ、双方向のアウトバウンド接続を確立します。Cloudflare Access は、その Cloudflare Tunnel を Hyperdrive 構成だけがアクセスできるように保護します。

すべてのチュートリアルは、Cloudflare Workers アカウント、C3 ↗、および Wrangler のセットアップが完了している前提です。セットアップは Get started ガイド で行います。

• プライベートネットワーク内のデータベース。TLS/SSL を使うように設定 されていること。
• Cloudflare アカウント上のホスト名。データベースへのリクエストのルーティングに使います。

まず、プライベートネットワーク内に Cloudflare Tunnel を作成し、ネットワークと Cloudflare の間に安全な接続を確立します。トンネルが Cloudflare ネットワークへ egress でき、ネットワーク内のデータベースへアクセスできるよう、権限を設定してください。

1. Cloudflare ダッシュボードにログインし、Networking > Tunnels を開きます。

   Tunnels を開く ↗

2. Create a tunnel を選択します。

3. トンネルの名前を入力します。このトンネル経由で接続するリソースの種類がわかる名前（例: enterprise-VPC-01）を推奨します。

4. Create Tunnel を選択します。

5. オペレーティングシステムを選び、インストールコマンドをコピーして、オリジンサーバーのターミナルで実行します。

6. トンネルの接続を待ちます。接続が確立したら Continue を選択します。

Hyperdrive がリクエストをルーティングできるよう、トンネルは Cloudflare 上の公開ホスト名を使うように設定する必要があります。まだ Cloudflare 上にホスト名がない場合は、先に 新しいホスト名を登録 するか、Cloudflare に ゾーンを追加 してください。

1. Published application routes タブで Domain を選び、サブドメインまたはパスを指定します。この値は、このトンネルへルーティングするために Hyperdrive 構成で使います。

2. Service セクションで、Type に TCP を指定し、データベースの URL と設定済みポート（localhost:5432 や my-database-host.database-provider.com:5432 など）を入力します。トンネルはこのアドレスで、リクエストをデータベースへルーティングします。

3. Save tunnel を選択します。

Cloudflare Tunnel へのアクセスを Hyperdrive に限定するには、有効な Service Auth トークン をリクエストに必須とする ポリシー を付けた Cloudflare Access アプリケーション を設定します。

Cloudflare ダッシュボードは、必要な Cloudflare Access アプリケーション、Service Auth トークン、ポリシー を自動で作成して設定できます。Access アプリケーションとポリシーを手動で作成することもできます。

# wrangler v3.65 and above required
npx wrangler hyperdrive create <NAME-OF-HYPERDRIVE-CONFIGURATION-FOR-DB-VIA-TUNNEL> --host=<HOSTNAME-FOR-THE-TUNNEL> --user=<USERNAME-FOR-YOUR-DATABASE> --password=<PASSWORD-FOR-YOUR-DATABASE> --database=<DATABASE-TO-CONNECT-TO> --access-client-id=<YOUR-ACCESS-CLIENT-ID> --access-client-secret=<YOUR-SERVICE-TOKEN-CLIENT-SECRET>

resource "cloudflare_hyperdrive_config"  "<TERRAFORM_VARIABLE_NAME_FOR_CONFIGURATION>" {
  account_id = "<YOUR_ACCOUNT_ID>"
  name       = "<NAME_OF_HYPERDRIVE_CONFIGURATION>"
  origin     = {
    host     = "<HOSTNAME_OF_TUNNEL>"
    database = "<NAME_OF_DATABASE>"
    user     = "<NAME_OF_DATABASE_USER>"
    password = "<DATABASE_PASSWORD>"
    scheme   = "postgres"
    access_client_id     = "<ACCESS_CLIENT_ID>"
    access_client_secret = "<ACCESS_CLIENT_SECRET>"
  }
  caching = {
    disabled = false
  }
}

Cloudflare Tunnel と Access 経由のデータベース接続をテストするには、Hyperdrive 構成 ID を Worker で使い、デプロイします。

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

Workers からデータベースに接続でき、クエリを実行できることを確認します。

npm i pg@>8.16.3

yarn add pg@>8.16.3

pnpm add pg@>8.16.3

bun add pg@>8.16.3

npm i -D @types/pg

yarn add -D @types/pg

pnpm add -D @types/pg

bun add -d @types/pg

{
	// 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>"

// filepath: src/index.ts
import { Client } from "pg";

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

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

			// Perform a simple query
			const result = await client.query("SELECT * FROM pg_tables");

			return Response.json({
				success: true,
				result: result.rows,
			});
		} catch (error: any) {
			console.error("Database error:", error.message);

			return new Response("Internal error occurred", { status: 500 });
		}
	},
};

npx wrangler deploy

npm i mysql2@>3.13.0

yarn add mysql2@>3.13.0

pnpm add mysql2@>3.13.0

bun add mysql2@>3.13.0

{
	// 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>"

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

npx wrangler deploy

トンネル経由でプライベートデータベースへ接続する Hyperdrive 構成で問題が起きた場合は、Hyperdrive の 一般的なトラブルシューティング手順 に加えて、次のよくある対処を確認してください。

• データベースが TLS（SSL）を使うように設定されていることを確認します。Hyperdrive の接続には TLS（SSL）が必要です。