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

この例では、Workers VPC と Hyperdrive を使い、Worker からプライベートな PostgreSQL データベースをクエリします。Worker はパブリックインターネットに出ていないデータベースへ接続し、Hyperdrive がコネクションプーリングとクエリ高速化を提供します。

前提条件

プライベートネットワーク上で稼働する PostgreSQL データベース（例: ポート 5432）
データベースが動くプライベートネットワークに接続した Cloudflare Tunnel
Workers VPC を利用できる Cloudflare アカウント

1. Cloudflare Tunnel を用意する

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

Workers VPC ダッシュボード ↗ を開き、Tunnels タブを選びます。
Create を選び、トンネルを作成します。
トンネル名を入力し、Save tunnel を選びます。
オペレーティングシステムとアーキテクチャを選びます。ダッシュボードにインストール手順が表示されます。
表示されたコマンドに従い、cloudflared をダウンロード、インストールし、固有のトークン付きで実行します。

トンネルは、プライベートネットワーク内からデータベースのホストとポートへ到達できる必要があります。トンネルの詳細は Workers VPC 向け Cloudflare Tunnel を参照してください。

2. TCP の VPC Service を作成する

データベースを指す、種別 tcp の 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>

<YOUR_TUNNEL_ID> をステップ 1 のトンネル ID に、<YOUR_DATABASE_IP> をデータベースのプライベート IP アドレス（例: 10.0.0.5）に置き換えます。

コマンドはサービス ID を返します。次のステップで使うため、この値を保存します。

3. Hyperdrive の設定を作成する

--service-id フラグで、作成した VPC Service を Hyperdrive の接続先にします。

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

<YOUR_VPC_SERVICE_ID> をステップ 2 のサービス ID に置き換え、データベース名、ユーザー、パスワードを指定します。

コマンドは Hyperdrive の設定 ID を出力します。次のステップで使うため、コピーします。

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

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

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

npm i pg@>8.16.3

yarn add pg@>8.16.3

pnpm add pg@>8.16.3

bun add pg@>8.16.3

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

npm i -D @types/pg

yarn add -D @types/pg

pnpm add -D @types/pg

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

6. デプロイして確認する

Worker をデプロイします。

npx wrangler deploy

接続を確認するリクエストを送ります。

curl https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev

成功すると、データベースの行を含む JSON 配列が返ります。

次のステップ

Hyperdrive の仕組みを確認する
Hyperdrive のクエリキャッシュを設定する
TLS 証明書検証を含む VPC Service の設定オプションを確認する
ほかの例を見る