cloudflare-hyperdrive

Cloudflare Hyperdrive

ステータス：本番環境対応 ✅ 最終更新日：2026-01-09 依存関係：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 回のラウンドトリップを排除）

---

既知の問題の予防

このスキルでは、情報源と解決策が記載された 11 件の既知の問題を予防できます。

問題 #1：Windows/macOS のローカル開発でホスト名の解決に失敗する

エラー：xxx.hyperdrive.local のようなホスト名で接続に失敗する 情報源：GitHub Issue #11556 プラットフォーム：Windows、macOS 26 Tahoe、Ubuntu 24.04 LTS（[email protected]+） 発生する理由：一部のプラットフォームでは Hyperdrive のローカルプロキシのホスト名を解決できません 予防策：

ローカル開発では環境変数を使用します。

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

または、wrangler dev --remote を使用します（本番データベースが使われるため注意してください）。

ステータス：未解決の問題ですが、回避策があります

---

問題 #2：postgres.js が IP アドレスでハングする

エラー：エラーメッセージが表示されず、接続がいつまでも完了しない 情報源：GitHub Issue #6179 発生する理由：接続文字列でホスト名の代わりに IP アドレスを使用すると、postgres.js がハングします 予防策：

// ❌ WRONG - IP address causes indefinite hang
const connection = "postgres://user:[email protected]:5432/db"

// ✅ CORRECT - Use hostname
const connection = "postgres://user:[email protected]:5432/db"

追加の注意点：Miniflare（ローカル開発）では、Postgres で特殊文字が許可されている場合でも、パスワードに使用できるのは A-z0-9 文字のみです。ローカル開発では、シンプルなパスワードを使用してください。

---

問題 #3：MySQL 8.0.43 の認証プラグインがサポートされていない

エラー：「サポートされていない認証方式」 情報源：GitHub Issue #10617 発生する理由：MySQL 8.0.43 以降では、Hyperdrive がサポートしていない新しい認証方式が導入されています 予防策：

MySQL 8.0.40 以前を使用するか、サポートされている認証プラグインを使用するようにユーザーを設定します。

ALTER USER 'username'@'%' IDENTIFIED WITH caching_sha2_password BY 'password';

サポートされている認証プラグイン：caching_sha2_password と mysql_native_password のみ ステータス：既知の問題として CFSQL-1392 で追跡中

---

Issue #4: リモートデータベースでローカルの SSL/TLS がサポートされない

エラー: SSL が必須ですが、ローカル開発で接続に失敗します ソース: GitHub Issue #10124 原因: Hyperdrive のローカルモードでは、リモートデータベース（Neon、クラウドプロバイダーなど）への SSL 接続がサポートされません 予防策:

コード内で条件付き接続を使用します。

const url = env.isLocal ? env.DB_URL : env.HYPERDRIVE.connectionString;
const client = postgres(url, {
  fetch_types: false,
  max: 2,
});

代替策: wrangler dev --remote を使用します（⚠️ 本番データベースに接続します） 予定: SSL サポートは 2026 年に予定されています（workerd／Workers ランタイムの変更が必要で、SQC-645 として追跡されています）

---

Issue #5: トランザクションモードではクエリ間で SET ステートメントがリセットされる

エラー: SET ステートメントがクエリ間で保持されません ソース: Cloudflare Hyperdrive Docs - How Hyperdrive Works 原因: Hyperdrive はトランザクションモードで動作し、各トランザクションの後に接続がプールに戻されてリセットされます 予防策:

// ❌ WRONG - SET won't persist across queries
await client.query('SET search_path TO myschema');
await client.query('SELECT * FROM mytable'); // Uses default search_path!

// ✅ CORRECT - SET within transaction
await client.query('BEGIN');
await client.query('SET search_path TO myschema');
await client.query('SELECT * FROM mytable'); // Now uses myschema
await client.query('COMMIT');

⚠️ 警告: SET の状態を維持するために複数の操作を 1 つのトランザクションにまとめると、Hyperdrive のパフォーマンスとスケーリングに影響します。

---

Issue #6: Prisma クライアントの再利用により Workers でハングする（コミュニティからの情報）

エラー: 最初のリクエストの後、Worker がハングしてタイムアウトします ソース: GitHub Issue #28193 確認状況: 複数のユーザーが確認しています 原因: Prisma の接続プールは、リクエストコンテキスト間で接続を再利用しようとするため、Workers の I/O 分離に違反します 予防策:

// ❌ WRONG - Global Prisma client reused across requests
const prisma = new PrismaClient({ adapter });

export default {
  async fetch(request: Request, env: Bindings) {
    // First request: works
    // Subsequent requests: hang indefinitely
    const users = await prisma.user.findMany();
    return Response.json({ users });
  }
};

// ✅ CORRECT - Create new client per request
export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const pool = new Pool({
      connectionString: env.HYPERDRIVE.connectionString,
      max: 5
    });
    const adapter = new PrismaPg(pool);
    const prisma = new PrismaClient({ adapter });

    try {
      const users = await prisma.user.findMany();
      return Response.json({ users });
    } finally {
      ctx.waitUntil(pool.end());
    }
  }
};

---

Issue #7: Neon Serverless Driver は Hyperdrive と互換性がない（コミュニティからの情報）

エラー: Neon のサーバーレスドライバーでは Hyperdrive のメリットが得られません ソース: Neon GitHub Repo、Cloudflare Docs 原因: Neon のサーバーレスドライバーは TCP ではなく WebSockets を使用するため、Hyperdrive の接続プールを経由しません 予防策:

// ❌ WRONG - Neon serverless driver bypasses Hyperdrive
import { neon } from '@neondatabase/serverless';
const sql = neon(env.HYPERDRIVE.connectionString);
// This uses WebSockets, not TCP - Hyperdrive doesn't help

// ✅ CORRECT - Use traditional TCP driver with Hyperdrive
import postgres from 'postgres';
const sql = postgres(env.HYPERDRIVE.connectionString, {
  prepare: true,
  max: 5
});

公式の推奨事項: Neon のドキュメントでは、「Cloudflare Workers では、このドライバーの代わりに Cloudflare Hyperdrive の使用を検討してください」と記載されています

---

Issue #8: Supabase ではプール済みではなく、直接接続文字列を使用する必要がある（コミュニティからの情報）

エラー: 二重のプールによって接続の問題が発生します ソース: Cloudflare Docs - Supabase 原因: Supabase のプール済み接続（Supavisor）を使用すると二重のプールが発生します。また、Supavisor は準備済みステートメントをサポートしていません 予防策:

# ❌ WRONG - Using Supabase pooled connection (Supavisor)
npx wrangler hyperdrive create my-supabase \
  --connection-string="postgres://user:[email protected]:6543/postgres"

# ✅ CORRECT - Use Supabase direct connection
npx wrangler hyperdrive create my-supabase \
  --connection-string="postgres://user:[email protected]:5432/postgres"

理由: Hyperdrive は独自のプールを提供します。二重のプールは問題を引き起こし、キャッシュを破損させます

---

Issue #9: Nitro 3 での Drizzle ORM — useDatabase の失敗率が 95%（コミュニティからの情報）

エラー: 約 95% の確率で 500 エラーが発生します ソース: GitHub Issue #3893 確認状況: 複数のユーザーが再現しています 原因: Nitro 3 に組み込まれている useDatabase（db0/integrations/drizzle）には、I/O 分離に関する問題があります 予防策:

// ❌ WRONG - Nitro's useDatabase fails ~95% of the time
import { useDatabase } from 'db0';
import { drizzle } from 'db0/integrations/drizzle';

export default eventHandler(async () => {
  const db = useDatabase();
  const users = await drizzle(db).select().from(usersTable);
  // Fails ~95% of the time with 500 error
});

// ✅ CORRECT - Create Drizzle client directly
import postgres from 'postgres';
import { drizzle } from 'drizzle-orm/postgres-js';

export default eventHandler(async (event) => {
  const sql = postgres(event.context.cloudflare.env.HYPERDRIVE.connectionString, {
    max: 5,
    prepare: true
  });
  const db = drizzle(sql);
  const users = await db.select().from(usersTable);
  event.context.cloudflare.ctx.waitUntil(sql.end());
  return { users };
});

エラーメッセージ: "Cannot perform I/O on behalf of a different request"

---

Issue #10: キャッシュに必要な postgres.js のバージョン（コミュニティからの情報）

エラー: 準備済みステートメントのキャッシュが正しく機能しません ソース: Cloudflare Docs 原因: 3.4.5 より前の postgres.js バージョンでは、Hyperdrive の準備済みステートメントのキャッシュが正しくサポートされません 予防策:

# Minimum version for Hyperdrive compatibility
npm install [email protected]

# Current recommended version
npm install [email protected]

関連情報: 2025 年 5 月の準備済みステートメントのキャッシュ改善には、最低でもバージョン 3.4.5 が必要です

---

Issue #11：WebSocket ベースのデータベースドライバーは互換性がありません

エラー：Hyperdrive の効果が得られない、または接続の問題が発生します
ソース：Neon serverless driver の問題で見られる一般的なパターン
原因：Hyperdrive には TCP 接続が必要ですが、WebSocket ベースのドライバーは TCP プーリングレイヤーを経由しません
予防策：

WebSocket ベースのドライバーではなく、従来の TCP ベースのドライバー（pg、postgres.js、mysql2）を使用してください。

影響を受けるドライバー：TCP ではなく WebSocket を使用するすべてのデータベースドライバー

---

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 月：Free プラン（10 個の設定）と Paid プラン（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

⚠️ 重要：Workers でリクエストをまたいで Prisma クライアントを再利用しないでください。リクエストごとに新しいクライアントを作成してください。

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

// ❌ WRONG - Global client causes hangs after first request
const prisma = new PrismaClient({ adapter });

export default {
  async fetch(request: Request, env: Bindings) {
    const users = await prisma.user.findMany(); // Hangs after first request
    return Response.json({ users });
  }
};

// ✅ CORRECT - Per-request client
export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const pool = new Pool({ connectionString: env.HYPERDRIVE.connectionString, max: 5 });
    const adapter = new PrismaPg(pool);
    const prisma = new PrismaClient({ adapter });

    try {
      const users = await prisma.user.findMany();
      return Response.json({ users });
    } finally {
      ctx.waitUntil(pool.end());
    }
  }
};

理由：Prisma の接続プールは、リクエストコンテキストをまたいで接続を再利用しようとするため、Workers の I/O 分離に違反します。ソース：GitHub Issue #28193

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

---

ローカル開発

⚠️ ローカル開発における SSL/TLS の制限

重要：ローカルの Hyperdrive 接続では SSL をサポートしていません。これは、SSL を必須とするデータベース（例：Neon、ほとんどのクラウドプロバイダー）に影響します。

回避策 — 条件付き接続：

const url = env.isLocal ? env.DB_URL : env.HYPERDRIVE.connectionString;
const client = postgres(url, {
  fetch_types: false,
  max: 2,
});

代替方法：wrangler dev --remote を使用します（⚠️ 本番データベースに接続します）

予定：SSL サポートは 2026 年を予定しています（workerd/Workers ランタイムの変更が必要） ソース：GitHub Issue #10124、SQC-645 として追跡中

---

ローカル接続のオプション

オプション 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 で複数ステートメントのクエリを使用する（サポートされていません） ❌ データベース認証情報をバージョン管理にコミットする ❌ 接続文字列でホスト名の代わりに IP アドレスを使用する（postgres.js がハングする原因になります） ❌ Hyperdrive で Neon serverless driver を使用する（WebSockets を使用し、プーリングを迂回します） ❌ Hyperdrive で Supabase のプール済み接続文字列（Supavisor）を使用する（二重プーリングになります） ❌ Workers でリクエストをまたいで Prisma クライアントのインスタンスを再利用する（ハングやタイムアウトの原因になります） ❌ Drizzle と Hyperdrive で Nitro 3 の useDatabase を使用する（約 95％ の確率で失敗します） ❌ SET ステートメントがクエリ間で維持されると想定する（トランザクションモードでは接続がリセットされます） ❌ postgres.js のバージョン 3.4.5 未満を使用する（プリペアドステートメントのキャッシュが機能しなくなります）

---

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 の分析機能で監視する - キャッシュヒット率とレイテンシを追跡します
9. ⚠️ SET ステートメントの永続性 - トランザクションモードでは、SET コマンドはクエリ間で維持されません。必要に応じて SET とクエリを BEGIN/COMMIT で囲んでください（パフォーマンスに影響します）

---

トラブルシューティング

解決策を含むエラーの完全なリファレンスについては、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 ダッシュボード → 設定を選択 → メトリクスタブ

利用可能な項目：クエリ数、キャッシュヒット率、クエリレイテンシ（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 コマンド
• サポート対象のデータベース

---

最終確認日：2026-01-21 | スキルバージョン：3.0.0 | 変更点：既知の問題を防ぐ項目を11件追加（TIER 1 が6件、TIER 2 が5件）、Prisma／ローカル開発／パフォーマンスのセクションに重要な警告を追加、「決して行わないこと」のルールを更新

パッケージバージョン：[email protected]、[email protected]+（最小）、[email protected]+（キャッシュに必要な最小バージョン）、[email protected]（推奨）、[email protected] 本番環境でのテスト：Cloudflare の公式ドキュメントとコミュニティの事例に基づいています