cloudflare-hyperdrive

Cloudflare Hyperdrive

ステータス：本番環境で利用可能 ✅ 最終更新日：2025-11-23 依存関係：cloudflare-worker-base（Worker のセットアップに推奨） 最新バージョン：[email protected]、[email protected]+（最小バージョン）、[email protected]、[email protected]

最近の更新（2025年）：

• 2025年7月：接続数を設定可能に（最小5、最大は無料プランで約20、有料プランで約100）
• 2025年5月：キャッシュヒットが5倍高速化（リージョン別のプリペアドステートメントキャッシュ）、FedRAMP Moderate 認可
• 2025年4月：無料プランで利用可能に（設定数10）、MySQL の GA サポート
• 2025年3月：レイテンシーを90％削減（データベースの近くにプールを配置）、IP アクセス制御（標準の CF IP 範囲）
• nodejs_compat_v2：pg ドライバーで node_compat モードが不要に（compatibility_date 2024-09-23+ で自動的に有効）
• 制限：アカウントあたりの Hyperdrive 設定数は、有料プランで25、無料プランで10

---

クイックスタート（5分）

1. Hyperdrive 設定を作成する

# For PostgreSQL
npx wrangler hyperdrive create my-postgres-db \
  --connection-string="postgres://user:[email protected]:5432/database"

# For MySQL
npx wrangler hyperdrive create my-mysql-db \
  --connection-string="mysql://user:[email protected]:3306/database"

# Output:
# ✅ Successfully created Hyperdrive configuration
#
# [[hyperdrive]]
# binding = "HYPERDRIVE"
# id = "a76a99bc-7901-48c9-9c15-c4b11b559606"

id の値を保存してください。次のステップで必要になります！

---

2. wrangler.jsonc でバインディングを設定する

wrangler.jsonc に以下を追加します。

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat"],  // REQUIRED for database drivers
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",                     // Available as env.HYPERDRIVE
      "id": "a76a99bc-7901-48c9-9c15-c4b11b559606"  // From wrangler hyperdrive create
    }
  ]
}

重要：

• すべてのデータベースドライバーで nodejs_compat フラグが必須です
• binding を使ってコードから Hyperdrive にアクセスします（env.HYPERDRIVE）
• id は Hyperdrive 設定 ID です（データベース ID ではありません）

---

3. データベースドライバーをインストールする

# For PostgreSQL (choose one)
npm install pg           # node-postgres (most common)
npm install postgres     # postgres.js (modern, minimum v3.4.5)

# For MySQL
npm install mysql2       # mysql2 (minimum v3.13.0)

---

4. データベースにクエリを実行する

node-postgres（pg）を使った PostgreSQL：

import { Client } from "pg";

type Bindings = {
  HYPERDRIVE: Hyperdrive;
};

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString
    });

    await client.connect();

    try {
      const result = await client.query('SELECT * FROM users LIMIT 10');
      return Response.json({ users: result.rows });
    } finally {
      // Clean up connection AFTER response is sent
      ctx.waitUntil(client.end());
    }
  }
};

mysql2 を使った MySQL：

import { createConnection } from "mysql2/promise";

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const connection = await createConnection({
      host: env.HYPERDRIVE.host,
      user: env.HYPERDRIVE.user,
      password: env.HYPERDRIVE.password,
      database: env.HYPERDRIVE.database,
      port: env.HYPERDRIVE.port,
      disableEval: true  // REQUIRED for Workers (eval() not supported)
    });

    try {
      const [rows] = await connection.query('SELECT * FROM users LIMIT 10');
      return Response.json({ users: rows });
    } finally {
      ctx.waitUntil(connection.end());
    }
  }
};

---

5. デプロイする

npx wrangler deploy

以上です！ Worker は Hyperdrive 経由で既存のデータベースに接続し、次の機能を利用できます。

• ✅ グローバルな接続プーリング
• ✅ クエリの自動キャッシュ
• ✅ レイテンシーの削減（7回の往復通信を解消）

---

Hyperdrive の仕組み

Hyperdrive は、接続時の7回の往復通信（TCP + TLS + 認証）を次の方法で解消します。

• Worker の近くでエッジ接続を確立（低レイテンシー）
• データベースの近くで接続をプーリング（2025年3月：レイテンシーを90％削減）
• エッジでクエリをキャッシュ（2025年5月：キャッシュヒットが5倍高速化）

結果：単一リージョンのデータベースを、グローバルに分散しているように利用できます。

---

セットアップ手順

前提条件

• Workers にアクセスできる Cloudflare アカウント
• PostgreSQL（v9.0-17.x）または MySQL（v5.7-8.x）データベース
• パブリックインターネット（TLS/SSL 必須）またはプライベートネットワーク（Cloudflare Tunnel）経由でアクセスできるデータベース
• 2025年4月：無料プラン（設定数10）と有料プラン（設定数25）で利用可能

接続文字列の形式

# PostgreSQL
postgres://user:password@host:5432/database
postgres://user:password@host:5432/database?sslmode=require

# MySQL
mysql://user:password@host:3306/database

# URL-encode special chars: p@ssw$rd → p%40ssw%24rd

---

接続パターン

単一接続（pg.Client）

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query('SELECT ...');
ctx.waitUntil(client.end());  // CRITICAL: Non-blocking cleanup

用途：シンプルなクエリ、リクエストあたり1つのクエリ

接続プール（pg.Pool）

const pool = new Pool({
  connectionString: env.HYPERDRIVE.connectionString,
  max: 5  // CRITICAL: Workers limit is 6 connections (July 2025: configurable ~20 Free, ~100 Paid)
});
const [result1, result2] = await Promise.all([
  pool.query('SELECT ...'),
  pool.query('SELECT ...')
]);
ctx.waitUntil(pool.end());

用途：1つのリクエスト内での並列クエリ

接続のクリーンアップ規則

必ず ctx.waitUntil(client.end()) を使用してください。レスポンス送信後にノンブロッキングでクリーンアップできます。 await client.end() は絶対に使用しないでください。レスポンスをブロックし、レイテンシーが増加します。

---

ORM との統合

Drizzle ORM

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

const sql = postgres(env.HYPERDRIVE.connectionString, { max: 5 });
const db = drizzle(sql);
const allUsers = await db.select().from(users);
ctx.waitUntil(sql.end());

Prisma ORM

import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "@prisma/client";
import { Pool } from "pg";

const pool = new Pool({ connectionString: env.HYPERDRIVE.connectionString, max: 5 });
const adapter = new PrismaPg(pool);
const prisma = new PrismaClient({ adapter });
const users = await prisma.user.findMany();
ctx.waitUntil(pool.end());

注：Prisma ではドライバーアダプター（@prisma/adapter-pg）が必要です。

---

ローカル開発

オプション1：環境変数（推奨）

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/local_db"
npx wrangler dev

設定を安全にコミットでき、wrangler.jsonc に認証情報を含めずに済みます。

オプション2：wrangler.jsonc の localConnectionString

{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "prod-id", "localConnectionString": "postgres://..." }] }

⚠️ 認証情報をバージョン管理にコミットしないでください。

オプション3：リモート開発

npx wrangler dev --remote  # ⚠️ Uses PRODUCTION database

---

クエリキャッシュ

キャッシュ対象：SELECT（データを変更しないクエリ） キャッシュ対象外：INSERT、UPDATE、DELETE、揮発性関数（LASTVAL、LAST_INSERT_ID）

2025年5月：リージョン別のプリペアドステートメントキャッシュにより、キャッシュヒットが5倍高速化しました。

postgres.js で特に重要な設定：

const sql = postgres(env.HYPERDRIVE.connectionString, {
  prepare: true  // REQUIRED for caching
});

キャッシュの状態を確認する：

response.headers.get('cf-cache-status');  // HIT, MISS, BYPASS, EXPIRED

---

TLS/SSL の設定

SSL モード：require（デフォルト）、verify-ca（CA を検証）、verify-full（CA とホスト名を検証）

サーバー証明書（verify-ca/verify-full）：

npx wrangler cert upload certificate-authority --ca-cert root-ca.pem --name my-ca-cert
npx wrangler hyperdrive create my-db --connection-string="postgres://..." --ca-certificate-id <ID> --sslmode verify-full

クライアント証明書（mTLS）：

npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name my-cert
npx wrangler hyperdrive create my-db --connection-string="postgres://..." --mtls-certificate-id <ID>

---

プライベートデータベースへのアクセス（Cloudflare Tunnel）

プライベートネットワーク（VPC、オンプレミス）内のデータベースに接続します。

# 1. Install cloudflared (macOS: brew install cloudflare/cloudflare/cloudflared)
# 2. Create tunnel
cloudflared tunnel create my-db-tunnel

# 3. Configure config.yml
# tunnel: <TUNNEL_ID>
# ingress:
#   - hostname: db.example.com
#     service: tcp://localhost:5432

# 4. Run tunnel
cloudflared tunnel run my-db-tunnel

# 5. Create Hyperdrive
npx wrangler hyperdrive create my-private-db --connection-string="postgres://user:[email protected]:5432/database"

---

重要なルール

必ず行うこと

✅ compatibility_flags に nodejs_compat を含める ✅ 接続のクリーンアップには ctx.waitUntil(client.end()) を使う ✅ 接続プールの max: 5 を設定する（Workers の上限は 6） ✅ データベースで TLS/SSL を有効にする（Hyperdrive では必須です） ✅ キャッシュにはプリペアドステートメントを使う（postgres.js：prepare: true） ✅ mysql2 ドライバーでは disableEval: true を設定する ✅ try/catch でエラーを適切に処理する ✅ ローカル開発用の接続文字列には環境変数を使う ✅ デプロイ前に wrangler dev でローカルテストを行う

絶対に行わないこと

❌ nodejs_compat フラグを省略する（「No such module」エラーの原因になります） ❌ プライベート IP アドレスを直接使う（代わりに Cloudflare Tunnel を使ってください） ❌ await client.end() を使う（レスポンスをブロックするため、ctx.waitUntil() を使ってください） ❌ 接続プールの max を 5 より大きく設定する（Workers の接続上限 6 を超えます） ❌ すべてのクエリをトランザクションで囲む（接続の多重化が制限されます） ❌ SQL レベルの PREPARE/EXECUTE/DEALLOCATE を使う（サポートされていません） ❌ アドバイザリロックや LISTEN/NOTIFY を使う（PostgreSQL ではサポートされていない機能です） ❌ MySQL で複数ステートメントのクエリを使う（サポートされていません） ❌ データベースの認証情報をバージョン管理にコミットする

---

Wrangler コマンドリファレンス

# Create Hyperdrive configuration
wrangler hyperdrive create <name> --connection-string="postgres://..."

# List all Hyperdrive configurations
wrangler hyperdrive list

# Get details of a configuration
wrangler hyperdrive get <hyperdrive-id>

# Update connection string
wrangler hyperdrive update <hyperdrive-id> --connection-string="postgres://..."

# Delete configuration
wrangler hyperdrive delete <hyperdrive-id>

# Upload CA certificate
wrangler cert upload certificate-authority --ca-cert <file>.pem --name <name>

# Upload client certificate pair
wrangler cert upload mtls-certificate --cert <cert>.pem --key <key>.pem --name <name>

---

サポートされているデータベース

PostgreSQL（v9.0-17.x）：AWS RDS/Aurora、Google Cloud SQL、Azure、Neon、Supabase、PlanetScale、Timescale、CockroachDB、Materialize、Fly.io、pgEdge、Prisma Postgres

MySQL（v5.7-8.x）：AWS RDS/Aurora、Google Cloud SQL、Azure、PlanetScale、MariaDB（2025 年 4 月 GA）

サポート対象外：SQL Server、MongoDB、Oracle

---

サポート対象外の機能

PostgreSQL

• SQL レベルのプリペアドステートメント（PREPARE、EXECUTE、DEALLOCATE）
• アドバイザリロック
• LISTEN および NOTIFY
• セッションごとの状態変更

MySQL

• クエリ内の UTF-8 以外の文字
• USE ステートメント
• 複数ステートメントのクエリ
• プロトコルレベルのプリペアドステートメント（COM_STMT_PREPARE）
• COM_INIT_DB メッセージ
• caching_sha2_password または mysql_native_password 以外の認証プラグイン

回避策：サポート対象外の機能を使う場合は、（Hyperdrive を介さずに）2 つ目の直接接続クライアントを作成してください。

---

パフォーマンスに関するベストプラクティス

1. 長時間実行されるトランザクションを避ける - 接続の多重化が制限されます
2. プリペアドステートメントを使う - クエリキャッシュが有効になります（postgres.js：prepare: true）
3. プールの max: 5 を設定する - Workers の接続上限 6 以内に収まります
4. 不要な場合は fetch_types を無効にする - レイテンシが低減します（postgres.js）
5. クリーンアップには ctx.waitUntil() を使う - 接続のクローズがノンブロッキングになります
6. キャッシュしやすいクエリを使う - 複雑な結合より SELECT を優先します
7. 頻繁にクエリする列にインデックスを付ける - クエリのパフォーマンスが向上します
8. Hyperdrive の分析機能で監視する - キャッシュヒット率とレイテンシを追跡します

---

トラブルシューティング

解決策を含むエラーリファレンスの全容は、references/troubleshooting.md を参照してください。

すぐに試せる対処法：

エラー	解決策
"No such module 'node:*'"	compatibility_flags に nodejs_compat を追加する
"TLS not supported by database"	データベースで SSL/TLS を有効にする
"Connection refused"	ファイアウォールのルールを確認し、パブリックインターネットからの接続を許可するか、Tunnel を使う
"Failed to acquire connection"	クリーンアップには ctx.waitUntil() を使い、長時間のトランザクションを避ける
"Code generation from strings disallowed"	mysql2 の設定で disableEval: true を設定する
"Bad hostname"	DNS が名前解決できることを確認し、タイプミスがないか確認する
"Invalid database credentials"	ユーザー名とパスワードを確認する（大文字と小文字は区別されます）

---

メトリクスと分析

Hyperdrive ダッシュボード → 設定を選択 → Metrics タブ

利用可能：クエリ数、キャッシュヒット率、クエリレイテンシ（p50/p95/p99）、接続レイテンシ、クエリ／結果のバイト数、エラー率

---

認証情報のローテーション

# Option 1: Create new config (zero downtime)
wrangler hyperdrive create my-db-v2 --connection-string="postgres://new-creds..."
# Update wrangler.jsonc, deploy, delete old config

# Option 2: Update existing
wrangler hyperdrive update <id> --connection-string="postgres://new-creds..."

ベストプラクティス：ステージング用と本番用に個別の設定を用意します。

---

参考資料

• 公式ドキュメント
• スタートガイド
• Hyperdrive の仕組み
• クエリキャッシュ
• ローカル開発
• TLS/SSL 証明書
• トラブルシューティングガイド
• Wrangler コマンド
• サポート対象のデータベース

---

最終更新日：2025-11-23 パッケージバージョン：[email protected], [email protected]+（最小バージョン）, [email protected], [email protected] 本番環境でのテスト：Cloudflare の公式ドキュメントとコミュニティの事例に基づいています