cloudflare-hyperdrive

Cloudflare Hyperdrive

状态：已可用于生产环境 ✅ 最后更新：2025-10-22 依赖项：cloudflare-worker-base（建议用于 Worker 设置） 最新版本：[email protected]+、[email protected]+、[email protected]+、[email protected]+

---

快速入门（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 的工作原理

问题

从 Cloudflare 的 300 多个全球位置连接传统数据库会带来一些挑战：

1. 高延迟——每次连接都需要多次往返：

   • TCP 握手（1 次往返）
   • TLS 协商（3 次往返）
   • 数据库身份验证（3 次往返）
   • 总计：发送查询前需要 7 次往返

2. 连接数限制——传统数据库可处理的并发连接有限，分布式流量很容易耗尽连接数

解决方案

Hyperdrive 通过以下方式解决这些问题：

1. 边缘连接设置——在 Worker 附近完成连接握手（低延迟）
2. 连接池——数据库附近的连接池会重复利用连接（消除往返）
3. 查询缓存——在边缘缓存常用查询（减轻数据库负载）

结果：单区域数据库也能像全球分布式数据库一样运行。

---

完整设置流程

步骤 1：准备工作

你需要：

• 可访问 Workers 的 Cloudflare 账户
• 现有的 PostgreSQL（v9.0-17.x）或 MySQL（v5.7-8.x）数据库
• 数据库可通过以下方式访问：
  • 公共互联网（已启用 TLS/SSL），或
  • 私有网络（通过 Cloudflare Tunnel）

重要提示：Hyperdrive 要求使用 TLS/SSL。请确保数据库已启用加密。

---

步骤 2：创建 Hyperdrive 配置

选项 A：Wrangler CLI（推荐）

# PostgreSQL connection string format:
# postgres://username:password@hostname:port/database_name

npx wrangler hyperdrive create my-hyperdrive \
  --connection-string="postgres://myuser:[email protected]:5432/mydb"

# MySQL connection string format:
# mysql://username:password@hostname:port/database_name

npx wrangler hyperdrive create my-hyperdrive \
  --connection-string="mysql://myuser:[email protected]:3306/mydb"

选项 B：Cloudflare 控制面板

1. 前往 Hyperdrive 控制面板
2. 点击 创建配置
3. 输入连接详细信息：
   • 名称：my-hyperdrive
   • 协议：PostgreSQL 或 MySQL
   • 主机：db.example.com
   • 端口：5432（PostgreSQL）或 3306（MySQL）
   • 数据库：mydb
   • 用户名：myuser
   • 密码：mypassword
4. 点击 创建

连接字符串格式：

# PostgreSQL (standard)
postgres://user:password@host:5432/database

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

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

# With special characters in password (URL encode)
postgres://user:p%40ssw%24rd@host:5432/database  # p@ssw$rd

---

步骤 3：配置 Worker 绑定

在 wrangler.jsonc 中添加 Hyperdrive 绑定：

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

多个 Hyperdrive 配置：

{
  "hyperdrive": [
    {
      "binding": "POSTGRES_DB",
      "id": "postgres-hyperdrive-id"
    },
    {
      "binding": "MYSQL_DB",
      "id": "mysql-hyperdrive-id"
    }
  ]
}

在 Worker 中访问：

type Bindings = {
  POSTGRES_DB: Hyperdrive;
  MYSQL_DB: Hyperdrive;
};

export default {
  async fetch(request, env: Bindings, ctx) {
    // Access different databases
    const pgClient = new Client({ connectionString: env.POSTGRES_DB.connectionString });
    const mysqlConn = await createConnection({ host: env.MYSQL_DB.host, ... });
  }
};

---

步骤 4：安装数据库驱动

PostgreSQL 驱动：

# Option 1: node-postgres (pg) - Most popular
npm install pg
npm install @types/pg  # TypeScript types

# Option 2: postgres.js - Modern, faster (minimum v3.4.5)
npm install postgres@^3.4.5

MySQL 驱动：

# mysql2 (minimum v3.13.0)
npm install mysql2

驱动对比：

驱动	数据库	优点	缺点	最低版本
pg	PostgreSQL	最受欢迎、稳定、文档完善	比 postgres.js 稍慢	8.13.0+
postgres	PostgreSQL	更快、API 现代、支持流式处理	较新（社区示例较少）	3.4.5+
mysql2	MySQL	支持 Promise、预处理语句、速度快	在 Workers 中需要设置 disableEval: true	3.13.0+

---

步骤 5：在 Worker 中使用驱动

使用 pg 连接 PostgreSQL（客户端）：

import { Client } from "pg";

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

    await client.connect();

    try {
      // Run query
      const result = await client.query('SELECT $1::text as message', ['Hello from Hyperdrive!']);
      return Response.json(result.rows);
    } catch (error) {
      return new Response(`Database error: ${error.message}`, { status: 500 });
    } finally {
      // CRITICAL: Clean up connection after response
      ctx.waitUntil(client.end());
    }
  }
};

使用 pg 连接 PostgreSQL（用于并行查询的连接池）：

import { Pool } from "pg";

export default {
  async fetch(request: Request, env: { HYPERDRIVE: Hyperdrive }, ctx: ExecutionContext) {
    // Create pool (max 5 to stay within Workers' 6 connection limit)
    const pool = new Pool({
      connectionString: env.HYPERDRIVE.connectionString,
      max: 5  // CRITICAL: Workers limit is 6 concurrent external connections
    });

    try {
      // Run parallel queries
      const [users, posts] = await Promise.all([
        pool.query('SELECT * FROM users LIMIT 10'),
        pool.query('SELECT * FROM posts LIMIT 10')
      ]);

      return Response.json({
        users: users.rows,
        posts: posts.rows
      });
    } finally {
      ctx.waitUntil(pool.end());
    }
  }
};

使用 postgres.js 连接 PostgreSQL：

import postgres from "postgres";

export default {
  async fetch(request: Request, env: { HYPERDRIVE: Hyperdrive }, ctx: ExecutionContext) {
    const sql = postgres(env.HYPERDRIVE.connectionString, {
      max: 5,              // Max 5 connections (Workers limit: 6)
      fetch_types: false,  // Disable if not using array types (reduces latency)
      prepare: true        // CRITICAL: Enable prepared statements for caching
    });

    try {
      const users = await sql`SELECT * FROM users LIMIT 10`;
      return Response.json({ users });
    } finally {
      ctx.waitUntil(sql.end({ timeout: 5 }));
    }
  }
};

使用 mysql2 连接 MySQL：

import { createConnection } from "mysql2/promise";

export default {
  async fetch(request: Request, env: { HYPERDRIVE: Hyperdrive }, 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: eval() not supported in Workers
    });

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

---

连接模式

模式 1：单个连接（pg.Client）

使用场景：简单查询，每个请求执行一次查询

import { Client } from "pg";

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

优点：简单、直接 缺点：无法并行执行查询

---

模式 2：连接池（pg.Pool）

使用场景：单个请求中执行多个并行查询

import { Pool } from "pg";

const pool = new Pool({
  connectionString: env.HYPERDRIVE.connectionString,
  max: 5  // CRITICAL: Stay within Workers' 6 connection limit
});

const [result1, result2] = await Promise.all([
  pool.query('SELECT ...'),
  pool.query('SELECT ...')
]);

ctx.waitUntil(pool.end());

优点：支持并行查询，性能更佳 缺点：必须管理最大连接数

---

模式 3：清理连接

重要：始终使用 ctx.waitUntil() 在发送响应后清理连接：

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

    try {
      const result = await client.query('SELECT ...');
      return Response.json(result.rows);  // Response sent here
    } finally {
      // This runs AFTER response is sent (non-blocking)
      ctx.waitUntil(client.end());
    }
  }
};

为什么使用 ctx.waitUntil()？

• 允许 Worker 立即返回响应
• 在后台清理连接
• 防止连接泄漏

不要这样做：

await client.end();  // ❌ Blocks response, adds latency

---

ORM 集成

Drizzle ORM（PostgreSQL）

1. 安装依赖：

npm install drizzle-orm postgres dotenv
npm install -D drizzle-kit

2. 定义架构（src/db/schema.ts）：

import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core";

export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  name: varchar("name", { length: 255 }).notNull(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  createdAt: timestamp("created_at").defaultNow(),
});

3. 在 Worker 中使用：

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { users } from "./db/schema";

export default {
  async fetch(request, env: { HYPERDRIVE: Hyperdrive }, ctx) {
    const sql = postgres(env.HYPERDRIVE.connectionString, { max: 5 });
    const db = drizzle(sql);

    const allUsers = await db.select().from(users);

    ctx.waitUntil(sql.end());
    return Response.json({ users: allUsers });
  }
};

---

Prisma ORM（PostgreSQL）

1. 安装依赖：

npm install prisma @prisma/client
npm install pg @prisma/adapter-pg

2. 初始化 Prisma：

npx prisma init

3. 定义架构（prisma/schema.prisma）：

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  name      String
  email     String   @unique
  createdAt DateTime @default(now())
}

4. 生成 Prisma Client：

npx prisma generate --no-engine

5. 在 Worker 中使用：

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

export default {
  async fetch(request, env: { HYPERDRIVE: Hyperdrive }, ctx) {
    // Create driver adapter with Hyperdrive connection
    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());
    return Response.json({ users });
  }
};

重要：Prisma 需要使用驱动适配器（@prisma/adapter-pg）才能与 Hyperdrive 配合使用。

---

本地开发

选项 1：环境变量（推荐）

设置 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING> 环境变量：

# If your binding is named "HYPERDRIVE"
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/local_db"

# Start local dev server
npx wrangler dev

优点：

• wrangler.jsonc 中无需存放凭据
• 可以安全地提交配置文件
• 不同开发者可以使用不同的本地数据库

---

选项 2：在 wrangler.jsonc 中设置 localConnectionString

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "production-hyperdrive-id",
      "localConnectionString": "postgres://user:password@localhost:5432/local_db"
    }
  ]
}

注意：不要将真实凭据提交到版本控制中！

---

选项 3：远程开发

在本地开发期间连接到生产数据库：

npx wrangler dev --remote

警告：这会使用你的生产数据库。所做的更改无法撤销！

---

查询缓存

缓存内容

Hyperdrive 会自动缓存非变更查询（只读查询）：

-- ✅ Cached
SELECT * FROM articles WHERE published = true ORDER BY date DESC LIMIT 50;
SELECT COUNT(*) FROM users;
SELECT * FROM products WHERE category = 'electronics';

-- ❌ NOT Cached
INSERT INTO users (name, email) VALUES ('John', '[email protected]');
UPDATE posts SET published = true WHERE id = 123;
DELETE FROM sessions WHERE expired = true;
SELECT LASTVAL();  -- PostgreSQL volatile function
SELECT LAST_INSERT_ID();  -- MySQL volatile function

工作原理

1. 线协议解析：Hyperdrive 解析数据库协议以区分变更操作
2. 自动检测：无需配置
3. 边缘缓存：缓存在 Cloudflare 边缘（靠近用户的位置）
4. 缓存失效：写入操作会使相关缓存查询失效

缓存优化

postgres.js — 启用预处理语句：

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

如果未设置 prepare: true，查询将无法缓存！

缓存状态

检查查询是否命中缓存：

const response = await fetch('https://your-worker.dev/api/users');
const cacheStatus = response.headers.get('cf-cache-status');
// Values: HIT, MISS, BYPASS, EXPIRED

---

TLS/SSL 配置

SSL 模式

Hyperdrive 支持 3 种 TLS/SSL 模式：

1. require（默认）— 必须使用 TLS，进行基本证书验证
2. verify-ca — 验证服务器证书是否由预期的 CA 签发
3. verify-full — 验证 CA，并确认主机名与证书 SAN 匹配

服务器证书（verify-ca / verify-full）

1. 上传 CA 证书：

npx wrangler cert upload certificate-authority \
  --ca-cert root-ca.pem \
  --name my-ca-cert

2. 使用 CA 创建 Hyperdrive：

npx wrangler hyperdrive create my-db \
  --connection-string="postgres://..." \
  --ca-certificate-id <CA_CERT_ID> \
  --sslmode verify-full

客户端证书（mTLS）

对于需要客户端身份验证的数据库：

1. 上传客户端证书和密钥：

npx wrangler cert upload mtls-certificate \
  --cert client-cert.pem \
  --key client-key.pem \
  --name my-client-cert

2. 使用客户端证书创建 Hyperdrive：

npx wrangler hyperdrive create my-db \
  --connection-string="postgres://..." \
  --mtls-certificate-id <CERT_PAIR_ID>

---

私有数据库访问（Cloudflare Tunnel）

将 Hyperdrive 连接到私有网络（VPC、本地部署环境）中的数据库：

1. 安装 cloudflared：

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64

2. 创建隧道：

cloudflared tunnel create my-db-tunnel

3. 配置隧道（config.yml）：

tunnel: <TUNNEL_ID>
credentials-file: /path/to/credentials.json

ingress:
  - hostname: db.example.com
    service: tcp://localhost:5432  # Your private database
  - service: http_status:404

4. 运行隧道：

cloudflared tunnel run my-db-tunnel

5. 创建 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()） ❌ 将连接池最大值设为大于 5（会超过 Workers 的 6 个连接限制） ❌ 将所有查询都包装在事务中（会限制连接多路复用） ❌ 使用 SQL 级别的 PREPARE/EXECUTE/DEALLOCATE（不受支持） ❌ 使用 advisory 锁、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 Database for PostgreSQL
• ✅ Neon
• ✅ Supabase
• ✅ PlanetScale（PostgreSQL）
• ✅ Timescale
• ✅ CockroachDB
• ✅ Materialize
• ✅ Fly.io
• ✅ pgEdge Cloud
• ✅ Prisma Postgres

MySQL（v5.7 - 8.x）

• ✅ AWS RDS / Aurora
• ✅ Google Cloud SQL
• ✅ Azure Database for MySQL
• ✅ PlanetScale（MySQL）

不支持

• ❌ SQL Server
• ❌ MongoDB（NoSQL）
• ❌ Oracle Database

---

不支持的功能

PostgreSQL

• SQL 级别的预处理语句（PREPARE、EXECUTE、DEALLOCATE）
• Advisory 锁
• 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 分析功能进行监控 - 跟踪缓存命中率和延迟

---

故障排除

完整的错误参考及解决方案请参阅 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 指标：

1. 前往 Hyperdrive Dashboard
2. 选择你的配置
3. 点击 指标 选项卡

可用指标：

• 查询数
• 缓存命中率（命中与未命中）
• 查询延迟（p50、p95、p99）
• 连接延迟
• 查询字节数 / 结果字节数
• 错误率

---

迁移策略

从直接数据库连接迁移

之前（直接连接）：

const client = new Client({
  host: 'db.example.com',
  user: 'myuser',
  password: 'mypassword',
  database: 'mydb',
  port: 5432
});

之后（使用 Hyperdrive）：

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

优点：

• ✅ 减少 7 次往返
• ✅ 启用查询缓存
• ✅ 自动连接池
• ✅ 提升全球性能

---

从 D1 迁移到 Hyperdrive

适合迁移的情况：

• 需要 PostgreSQL/MySQL 功能（JSON 类型、全文搜索等）
• 已有数据库和数据
• 多区域只读副本
• 高级索引策略

适合继续使用 D1 的情况：

• 正在构建新的 Cloudflare 原生应用
• SQLite 功能已足够
• 没有现有数据库需要迁移
• 希望使用更简单的无服务器设置

---

凭据轮换

选项 1：创建新的 Hyperdrive 配置

# Create new config with new credentials
wrangler hyperdrive create my-db-v2 --connection-string="postgres://..."

# Update wrangler.jsonc to use new ID
# Deploy gradually (no downtime)
# Delete old config when migration complete

选项 2：更新现有配置

wrangler hyperdrive update <id> --connection-string="postgres://new-credentials@..."

最佳实践：为预发布环境和生产环境使用单独的 Hyperdrive 配置。

---

示例

完整的可运行示例请参见 templates/ 目录：

• postgres-basic.ts - 使用 pg.Client 执行简单查询
• postgres-pool.ts - 使用 pg.Pool 执行并行查询
• postgres-js.ts - 使用 postgres.js 驱动程序
• mysql2-basic.ts - 使用 mysql2 驱动程序连接 MySQL
• drizzle-postgres.ts - Drizzle ORM 集成
• drizzle-mysql.ts - Drizzle ORM 与 MySQL 集成
• prisma-postgres.ts - Prisma ORM 集成

---

参考资料

• 官方文档
• 入门指南
• Hyperdrive 的工作原理
• 查询缓存
• 本地开发
• TLS/SSL 证书
• 故障排除指南
• Wrangler 命令
• 支持的数据库

---

最后更新：2025-10-22 软件包版本：[email protected]+、[email protected]+、[email protected]+、[email protected]+ 生产环境测试：基于 Cloudflare 官方文档和社区示例