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 正式支持
• 2025 年 3 月：延迟降低 90%（连接池靠近数据库）、IP 访问控制（标准 CF IP 范围）
• nodejs_compat_v2：pg 驱动不再需要 node_compat 模式（compatibility_date 为 2024-09-23+ 时会自动启用）
• 限制：每个账户最多 25 个 Hyperdrive 配置（付费版），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（本地开发）密码仅支持 A-z0-9 字符，尽管 Postgres 允许使用特殊字符。本地开发时请使用简单密码。

---

问题 #3：MySQL 8.0.43 不支持身份验证插件

错误："unsupported authentication method" 来源：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

---

问题 #4：远程数据库不支持本地 SSL/TLS

错误：需要 SSL，但在本地开发时连接失败 来源：GitHub 问题 #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（⚠️ 会连接到生产数据库） 时间表：计划于 2026 年支持 SSL（需要修改 workerd/Workers 运行时，跟踪编号为 SQC-645）

---

问题 #5：事务模式会在查询之间重置 SET 语句

错误：SET 语句不会在多个查询之间保留 来源：Cloudflare Hyperdrive 文档 - Hyperdrive 的工作原理 原因：Hyperdrive 以事务模式运行，每笔事务结束后，连接都会归还到连接池并执行 RESET 预防措施：

// ❌ 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 状态，会影响 Hyperdrive 的性能和扩展能力。

---

问题 #6：Prisma 客户端重用会导致 Workers 挂起（社区来源）

错误：Worker 在首次请求后挂起并超时 来源：GitHub 问题 #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());
    }
  }
};

---

问题 #7：Neon Serverless 驱动程序与 Hyperdrive 不兼容（社区来源）

错误：Hyperdrive 无法与 Neon Serverless 驱动程序协同发挥作用 来源：Neon GitHub 仓库，Cloudflare 文档 原因：Neon 的 Serverless 驱动程序使用 WebSockets 而非 TCP，因此会绕过 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，而非此驱动程序。”

---

问题 #8：Supabase - 必须使用直接连接字符串，而非连接池（社区来源）

错误：双重连接池会导致连接问题 来源：Cloudflare 文档 - 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 会提供自己的连接池；双重连接池会引发问题并破坏缓存

---

问题 #9：Drizzle ORM 与 Nitro 3 搭配使用时，useDatabase 的失败率达 95%（社区来源）

错误：约 95% 的情况下会出现 500 错误 来源：GitHub 问题 #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 };
});

错误消息：“无法代表其他请求执行 I/O”

---

问题 #10：postgres.js 的缓存版本要求（社区来源）

错误：预处理语句缓存无法正常工作 来源：Cloudflare 文档 原因：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 无服务器驱动问题的一般模式
原因：Hyperdrive 需要 TCP 连接；基于 WebSocket 的驱动会绕过 TCP 连接池层
预防措施：

使用传统的基于 TCP 的驱动（pg、postgres.js、mysql2），不要使用基于 WebSocket 的驱动。

受影响的驱动：任何使用 WebSocket 而非 TCP 的数据库驱动

---

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

适用于：简单查询，每个请求执行一次查询

连接池（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());

适用于：单个请求中并行执行查询

连接清理规则

务必使用 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（⚠️ 会连接到生产数据库）

时间安排：计划于 2026 年支持 SSL（需要修改 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 挂起） ❌ 将 Neon 无服务器驱动与 Hyperdrive 搭配使用（它使用 WebSockets，会绕过连接池） ❌ 将 Supabase 池化连接字符串（Supavisor）与 Hyperdrive 搭配使用（会造成双重连接池） ❌ 在 Workers 的多个请求之间重复使用 Prisma 客户端实例（会导致挂起和超时） ❌ 在 Drizzle 和 Hyperdrive 中使用 Nitro 3 的 useDatabase（失败率约为 95%） ❌ 认为 SET 语句会在后续查询中持续生效（事务模式会重置连接） ❌ 使用低于 3.4.5 的 postgres.js 版本（会破坏预处理语句缓存）

---

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 月正式发布）

不支持：SQL Server、MongoDB、Oracle

---

不支持的功能

PostgreSQL

• SQL 级别的预处理语句（PREPARE、EXECUTE、DEALLOCATE）
• 咨询锁
• LISTEN 和 NOTIFY
• 修改会话状态

MySQL

• 查询中使用非 UTF8 字符
• USE 语句
• 多语句查询
• 协议级别的预处理语句（COM_STMT_PREPARE）
• COM_INIT_DB 消息
• 除 caching_sha2_password 或 mysql_native_password 之外的身份验证插件

变通方法：对于不支持的功能，请创建第二个直接的客户端连接（不经过 Hyperdrive）。

---

性能最佳实践

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:*'"	将 nodejs_compat 添加到 compatibility_flags
"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 命令
• 支持的数据库

---

上次验证：2026-01-21 | 技能版本：3.0.0 | 变更：新增 11 条已知问题预防条目（6 条 TIER 1、5 条 TIER 2），扩展 Prisma/本地开发/性能部分并添加重要警告，更新“绝不执行”规则

软件包版本：[email protected]、[email protected]+（最低版本）、[email protected]+（缓存所需最低版本）、[email protected]（推荐版本）、[email protected] 生产环境测试：基于 Cloudflare 官方文档和社区示例