cloudflare-hyperdrive

Cloudflare Hyperdrive

ステータス：本番環境で使用可能 ✅ | 最終確認日：2025-11-18

---

Hyperdrive とは？

Worker を既存の PostgreSQL／MySQL データベースに接続します：

• グローバルなコネクションプーリング
• クエリキャッシュ
• レイテンシの低減
• node-postgres、postgres.js、mysql2 に対応

---

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

1. Hyperdrive の設定を作成する

bunx wrangler hyperdrive create my-db \
  --connection-string="postgres://user:pass@host:5432/database"

id を保存してください！

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

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat"],  // REQUIRED!
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<ID_FROM_STEP_1>"
    }
  ]
}

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

bun add pg  # or postgres, or mysql2

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

import { Client } from 'pg';

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

    const result = await client.query('SELECT * FROM users LIMIT 10');
    await client.end();

    return Response.json(result.rows);
  }
};

手順の詳細については、references/setup-guide.md を読み込んでください。

---

重要なルール

必ず行うこと ✅

1. nodejs_compat フラグを有効にする（必須です！）
2. env.HYPERDRIVE.connectionString を使用する（元の DB 接続文字列は使用しないでください）
3. クエリ実行後に接続を閉じる
4. エラーを明示的に処理する
5. コネクションプーリングを使用する（組み込み機能）
6. wrangler dev でローカルテストを行う
7. クエリのパフォーマンスを監視する
8. プリペアドステートメントを使用する
9. クエリキャッシュを有効にする（自動）
10. 接続文字列を安全に管理する（シークレットを使用）

絶対に行わないこと ❌

1. nodejs_compat を省略しないでください（ドライバーが動作しません）
2. Worker で元の DB 接続文字列を使用しないでください
3. 接続を開いたままにしないでください（コネクションプールが枯渇します）
4. エラー処理を省略しないでください（DB が停止する可能性があります）
5. コードに認証情報をハードコードしないでください
6. 接続数の上限を超えないでください
7. eval/Function を使用しないでください（Worker ではブロックされています）
8. 本番環境の DB で TLS を省略しないでください
9. ブロッキングクエリを使用しないでください（Worker がタイムアウトします）
10. DB エラーをユーザーに公開しないでください

---

データベースドライバー

PostgreSQL（node-postgres）

import { Client } from 'pg';

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query('SELECT * FROM users');
await client.end();

PostgreSQL（postgres.js）

import postgres from 'postgres';

const sql = postgres(env.HYPERDRIVE.connectionString);
const users = await sql`SELECT * FROM users`;

MySQL

import mysql from 'mysql2/promise';

const connection = await mysql.createConnection(env.HYPERDRIVE.connectionString);
const [rows] = await connection.execute('SELECT * FROM users');
await connection.end();

---

Drizzle ORM との連携

import { drizzle } from 'drizzle-orm/node-postgres';
import { Client } from 'pg';

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();

const db = drizzle(client);
const users = await db.select().from(usersTable);

await client.end();

---

よくあるユースケース

ユースケース 1：読み取り専用クエリ

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

    const users = await client.query('SELECT * FROM users WHERE active = true');
    await client.end();

    return Response.json(users.rows);
  }
};

ユースケース 2：パラメーター化クエリ

const userId = new URL(request.url).searchParams.get('id');

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();

const result = await client.query(
  'SELECT * FROM users WHERE id = $1',
  [userId]
);

await client.end();

ユースケース 3：トランザクション

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();

try {
  await client.query('BEGIN');
  await client.query('UPDATE accounts SET balance = balance - 100 WHERE id = $1', [1]);
  await client.query('UPDATE accounts SET balance = balance + 100 WHERE id = $1', [2]);
  await client.query('COMMIT');
} catch (e) {
  await client.query('ROLLBACK');
  throw e;
} finally {
  await client.end();
}

---

対応データベース

PostgreSQL：

• Amazon RDS
• Amazon Aurora
• Neon
• Supabase
• Railway
• Render
• DigitalOcean
• PostgreSQL 11 以降

MySQL：

• Amazon RDS
• Amazon Aurora
• PlanetScale
• MySQL 5.7 以降

---

公式ドキュメント

• Hyperdrive の概要：https://developers.cloudflare.com/hyperdrive/
• はじめに：https://developers.cloudflare.com/hyperdrive/get-started/
• 設定：https://developers.cloudflare.com/hyperdrive/configuration/

---

同梱リソース

リファレンス（references/）：

• setup-guide.md - セットアップの全手順（設定の作成、バインド、クエリの実行）
• connection-pooling.md - コネクションプールの設定とベストプラクティス
• query-caching.md - クエリキャッシュの戦略と最適化
• drizzle-integration.md - Drizzle ORM の連携パターン
• prisma-integration.md - Prisma ORM の連携パターン
• supported-databases.md - 対応する PostgreSQL および MySQL プロバイダーの全一覧
• tls-ssl-setup.md - 安全な接続のための TLS/SSL 設定
• troubleshooting.md - よくある問題と解決方法
• wrangler-commands.md - Hyperdrive 用 wrangler CLI コマンドの全一覧

テンプレート（templates/）：

• postgres-basic.ts - node-postgres を使用した基本的な PostgreSQL
• postgres-js.ts - postgres.js ドライバーを使用した PostgreSQL
• postgres-pool.ts - コネクションプーリングを使用した PostgreSQL
• mysql2-basic.ts - mysql2 ドライバーを使用した MySQL
• drizzle-postgres.ts - PostgreSQL を使用する Drizzle ORM
• drizzle-mysql.ts - MySQL を使用する Drizzle ORM
• prisma-postgres.ts - PostgreSQL を使用する Prisma ORM
• local-dev-setup.sh - ローカル開発環境のセットアップスクリプト
• wrangler-hyperdrive-config.jsonc - Wrangler 設定例

---

質問や問題がある場合

1. セットアップの全手順については、references/setup-guide.md を確認してください
2. nodejs_compat フラグが有効になっていることを確認してください
3. env.HYPERDRIVE.connectionString を使用していることを確認してください
4. 接続が正しく閉じられていることを確認してください