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 ロール。
データベースと同じネットワークでトンネルがまだ稼働していない場合は、作成します。
-
Workers VPC ダッシュボード ↗ を開き、Tunnels タブを選びます。
-
Create を選び、トンネルを作成します。
-
トンネル名を入力し、Save tunnel を選びます。
-
オペレーティングシステムとアーキテクチャを選びます。ダッシュボードにインストール手順が表示されます。
-
表示されたコマンドに従い、
cloudflaredをダウンロード、インストールし、固有のトークン付きで実行します。
トンネルは、プライベートネットワーク内からデータベースのホストとポートに到達できる必要があります。
トンネルの詳細は Workers VPC 向け Cloudflare Tunnel を参照してください。
データベースを指す 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 を参照してください。
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 証明書の検証モード を参照してください。
--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 postgresqlnpx 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 をコピーします。
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>"node-postgres ↗(pg)でテストクエリを送信します。
node-postgres ドライバーをインストールします。
npm i pg@>8.16.3yarn add pg@>8.16.3pnpm add pg@>8.16.3bun add pg@>8.16.3TypeScript を使う場合は、型定義パッケージもインストールします。
npm i -D @types/pgyarn add -D @types/pgpnpm add -D @types/pgbun 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 });
}
},
};Worker をデプロイします。
npx wrangler deployデプロイした Worker にアクセスしたときにデータベースから pg_tables の一覧が返れば、Hyperdrive は Workers VPC 経由でプライベートデータベースに接続できています。
mysql2 ↗ でテストクエリを送信します。
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>;Worker をデプロイします。
npx wrangler deployデプロイした Worker にアクセスしたときにデータベースからテーブル一覧が返れば、Hyperdrive は Workers VPC 経由でプライベートデータベースに接続できています。
- Hyperdrive の仕組み を確認します。
- Hyperdrive の クエリキャッシュ を設定します。
- TLS 証明書の検証を含む VPC Service の設定オプション を確認します。
- 本番ワークロード向けに 高可用性トンネル をセットアップします。
- データベースを Hyperdrive に接続するときの よくある問題のトラブルシューティング を確認します。