Skip to content

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

Workers VPC でプライベートデータベースに接続する(推奨)

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

Workers VPC を使うと、Cloudflare Access アプリケーションやサービストークンを設定せずに、Hyperdrive をプライベートデータベースへ接続できます。データベースを指す TCP VPC Service を作成し、そのサービス ID を Hyperdrive に渡します。

Tunnel と Access を使う方法は、Tunnel でプライベートデータベースに接続する を参照してください。

仕組み

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

  • Cloudflare Tunnel で、プライベートネットワークから Cloudflare への安全なアウトバウンド接続を確立します。
  • VPC Service で、Worker からのトラフィックをトンネル経由でデータベースへルーティングします。Cloudflare Access アプリケーションやサービストークンは不要です。

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

flowchart LR
    A[Cloudflare Worker] --> B[Hyperdrive] --> C[VPC Service] --> D[Cloudflare Tunnel] --> E[プライベートデータベース]

始める前に

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

前提条件

  • プライベートネットワーク内のデータベース(TLS/SSL を使うよう設定済み)。
  • データベースに到達できるネットワーク上で稼働している Cloudflare Tunnel
  • VPC Service を作成するための、Cloudflare アカウントの Connectivity Directory Admin ロール。

1. Cloudflare Tunnel をセットアップする

データベースと同じネットワークでトンネルがまだ稼働していない場合は、作成します。

  1. Workers VPC ダッシュボード を開き、Tunnels タブを選びます。

  2. Create を選び、トンネルを作成します。

  3. トンネル名を入力し、Save tunnel を選びます。

  4. オペレーティングシステムとアーキテクチャを選びます。ダッシュボードにインストール手順が表示されます。

  5. 表示されたコマンドに従い、cloudflared をダウンロード、インストールし、固有のトークン付きで実行します。

トンネルは、プライベートネットワーク内からデータベースのホストとポートに到達できる必要があります。

トンネルの詳細は Workers VPC 向け Cloudflare Tunnel を参照してください。

2. TCP VPC Service を作成する

データベースを指す tcp タイプの VPC Service を作成します。Hyperdrive が接続を最適化できるよう、--app-protocol フラグを postgresql または mysql に設定します。

npx wrangler vpc service create my-postgres-db \
  --type tcp \
  --tcp-port 5432 \
  --app-protocol postgresql \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --ipv4 <YOUR_DATABASE_IP>
npx wrangler vpc service create my-mysql-db \
  --type tcp \
  --tcp-port 3306 \
  --app-protocol mysql \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --ipv4 <YOUR_DATABASE_IP>

次を置き換えます。

  • <YOUR_TUNNEL_ID> を手順 1 のトンネル ID にします。
  • <YOUR_DATABASE_IP> をデータベースのプライベート IP アドレス(例: 10.0.0.5)にします。--ipv4 の代わりに --hostname と DNS 名も使えます。

コマンドはサービス ID を返します。次の手順のためにこの値を保存します。

Workers VPC ダッシュボード から TCP VPC Service を作成することもできます。設定オプションの一覧は VPC Services を参照してください。

TLS 証明書の検証

Hyperdrive はデフォルトでオリジンサーバー証明書を検証しません。一方、Workers VPC のデフォルトは verify_full です。証明書チェーンとホスト名の両方を検証します。データベースが自己署名証明書、またはプライベート認証局(CA)の証明書を使う場合、検証モードを変更しないと TLS ハンドシェイクは失敗します。

自己署名証明書のデータベースでは、VPC Service 作成時に --cert-verification-mode を追加します。

  • verify_ca — 証明書チェーンは検証しますが、ホスト名の検証はスキップします。自分が管理する CA が署名した証明書を使う一方、ホスト名が証明書と一致しない場合に使います。
  • disabled — 証明書検証をすべてスキップします。開発またはテストでのみ使います。

たとえば、自己署名証明書の PostgreSQL データベース向けに VPC Service を作成するには:

npx wrangler vpc service create my-postgres-db \
  --type tcp \
  --tcp-port 5432 \
  --app-protocol postgresql \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --ipv4 <YOUR_DATABASE_IP> \
  --cert-verification-mode verify_ca

既存の VPC Service を更新するには、同じフラグ付きで wrangler vpc service update を使います。

検証モードの一覧は TLS 証明書の検証モード を参照してください。

3. Hyperdrive 構成を作成する

--service-id フラグで、作成した VPC Service を Hyperdrive に指定します。--service-id を使う場合、--origin-host--origin-port--connection-string は指定しません。Hyperdrive は VPC Service 経由でトラフィックをルーティングします。

npx wrangler hyperdrive create <YOUR_CONFIG_NAME> \
  --service-id <YOUR_VPC_SERVICE_ID> \
  --database <DATABASE_NAME> \
  --user <DATABASE_USER> \
  --password <DATABASE_PASSWORD> \
  --scheme postgresql
npx wrangler hyperdrive create <YOUR_CONFIG_NAME> \
  --service-id <YOUR_VPC_SERVICE_ID> \
  --database <DATABASE_NAME> \
  --user <DATABASE_USER> \
  --password <DATABASE_PASSWORD> \
  --scheme mysql

次を置き換えます。

  • <YOUR_VPC_SERVICE_ID> を手順 2 のサービス ID にします。
  • <DATABASE_NAME> をデータベース名にします。
  • <DATABASE_USER><DATABASE_PASSWORD> をデータベースの認証情報にします。

成功すると、コマンドは id フィールド付きの Hyperdrive 構成を出力します。次の手順のためにこの ID をコピーします。

4. Hyperdrive を 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>"

5. データベースをクエリする

node-postgrespg)でテストクエリを送信します。

node-postgres ドライバーをインストールします。

npm i pg@>8.16.3

TypeScript を使う場合は、型定義パッケージもインストールします。

npm i -D @types/pg

必要な 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>"

新しい Client インスタンスを作成し、Hyperdrive の connectionString を渡します。

// 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 });
		}
	},
};

Worker をデプロイします。

npx wrangler deploy

デプロイした Worker にアクセスしたときにデータベースから pg_tables の一覧が返れば、Hyperdrive は Workers VPC 経由でプライベートデータベースに接続できています。

mysql2 でテストクエリを送信します。

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

Worker をデプロイします。

npx wrangler deploy

デプロイした Worker にアクセスしたときにデータベースからテーブル一覧が返れば、Hyperdrive は Workers VPC 経由でプライベートデータベースに接続できています。

次のステップ

役に立ちましたか?