在 Cloudflare Workers 中连接 OB Cloud 云数据库

Cloudflare Workers 允许您在特定事件发生时在边缘节点运行代码，适用于构建自定义 API、无服务器函数和微服务，对低延迟与弹性扩展场景尤为适用。OceanBase Cloud 兼容 MySQL 协议，可与 Cloudflare Workers 通过 TCP 与 Hyperdrive 建立连接。

本文介绍如何创建 Cloudflare Workers 应用并连接至 OB Cloud 云数据库，实现与库中数据的交互。

前提条件

• 您已注册 OB Cloud 云数据库账号，并创建一个事务型实例和 MySQL 兼容模式租户。详情请参见 创建集群实例 和 创建租户。
• 已创建数据库及账号，且账号已具备读写权限。详情请参见 创建账号 和 创建数据库（仅 MySQL）。
• 您具备项目管理员或实例管理员角色，可对项目中实例进行读写操作；如无权限，请联系组织管理员添加。
• 已注册 Cloudflare 账号。
• 已安装 Node.js，且版本为 16.17.0 或更高（Wrangler CLI 依赖此版本）。

步骤一：获取数据库连接信息

1. 登录 OB Cloud 云数据库控制台。在实例列表页面，展开目标事务型实例的信息，在目标租户下，单击 连接 > 获取连接串。

2. 在弹出框中选择 公网连接。

3. 在 使用公共网络连接 页面完成如下设置，生成连接串：

   1. （可选）若租户没有已生成的公网地址，在 步骤 1: 获取公网地址 下，单击 获取公网地址 获取公网地址。若已有公网地址，可跳过此步骤。生成地址后，单击 下一步。

   2. 在 步骤 2: 安全设置 下，完成以下配置后，单击 下一步：

      • 添加 IP 地址白名单组：单击 添加，选择 允许所有 IP 访问（Workers 运行于 Cloudflare 边缘，需放通访问），单击 确定。

      • 下载证书：单击 下载 CA 证书 下载证书并完成认证。

   3. 在 步骤 3: 访问数据库 下，选择前提条件中创建的数据库和账号，并选择 MySQL CLI 作为连接方式。完成后，复制连接串，供后续配置 Hyperdrive 与 DATABASE_URL 使用。

步骤二：安装并配置 Wrangler

Wrangler 是 Cloudflare 官方提供的 Workers 命令行工具，用于创建、构建、预览和部署 Workers。

安装 Wrangler

npm install -g wrangler

配置环境变量

1. 在 Cloudflare 控制台 创建 API Token：

   1. 单击 Create Token。
   2. 选择 Edit Cloudflare Workers 模板，并添加 Hyperdrive 权限。
   3. 复制生成的 API Token。
   4. 进入 Workers & Pages 页面，记录 Account ID 和 Subdomain（子域名）。

2. 在本地终端中设置环境变量（将占位符替换为您的实际值）：

   export CLOUDFLARE_API_TOKEN="your-api-token-here"
   export CLOUDFLARE_ACCOUNT_ID="your-account-id"
   

创建 Worker 项目

1. 执行以下命令创建名为 oceanbase-tutorial 的 Worker 项目：

   wrangler init oceanbase-tutorial
   

2. 按提示选择以下选项：

   配置项	选择
   What would you like to start with?	Hello World example
   Which template would you like to use?	Worker only
   Which language do you want to use?	TypeScript
   Do you want to use git for version control?	Yes
   Do you want to deploy your application?	No

3. 创建完成后进入项目目录：

   cd oceanbase-tutorial
   

步骤三：配置 DATABASE_URL 密钥

DATABASE_URL 格式为：mysql://用户名:密码@主机:端口/数据库名。请使用 步骤一 中复制的连接信息拼成该格式。

在项目根目录下执行：

wrangler secret put DATABASE_URL

按提示输入您的 DATABASE_URL。设置成功后会看到：

✨ Success! Uploaded secret DATABASE_URL

步骤四：创建 Hyperdrive 并绑定到 Worker

创建 Hyperdrive 配置

使用 OB Cloud 连接串创建 Hyperdrive 配置。连接串格式为：mysql://用户名:密码@主机:端口/数据库名。

npx wrangler hyperdrive create oceanbase-hyperdrive --connection-string="mysql://username:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

请将 username、password、HOSTNAME_OR_IP_ADDRESS、PORT、database_name 替换为 步骤一 中获取的实际连接信息。命令执行后会输出 Hyperdrive 的 ID，请记录该 ID。

在 Wrangler 配置中绑定 Hyperdrive

根据您使用的配置文件类型，在项目根目录的 wrangler.jsonc 或 wrangler.toml 中增加 Hyperdrive 绑定，并将 YOUR_Hyperdrive_ID 替换为上一步得到的 ID。

• 使用 wrangler.jsonc：

  {
      "$schema": "node_modules/wrangler/config-schema.json",
      "name": "oceanbase-tutorial",
      "main": "src/index.ts",
      "compatibility_date": "2024-09-23",
      "compatibility_flags": [
          "nodejs_compat"
      ],
      "observability": {
          "enabled": true
      },
      "hyperdrive": [
          {
              "binding": "HYPERDRIVE",
              "id": "YOUR_Hyperdrive_ID"
          }
      ]
  }
  

• 使用 wrangler.toml：

  name = "oceanbase-tutorial"
  main = "src/index.ts"
  compatibility_date = "2024-09-23"
  compatibility_flags = ["nodejs_compat"]
  
  [observability]
  enabled = true
  
  [[hyperdrive]]
  binding = "HYPERDRIVE"
  id = "YOUR_Hyperdrive_ID"
  

步骤五：安装依赖并编写 Worker 代码

安装 mysql2 驱动

需使用 mysql2 v3.13.0 或更高版本。在项目根目录执行其一即可：

npm i mysql2@">=3.13.0"
# 或
yarn add mysql2@">=3.13.0"
# 或
pnpm add mysql2@">=3.13.0"

编写 Worker 入口代码

编辑 src/index.ts，使用 Hyperdrive 绑定连接 OceanBase 并执行一次简单查询，用于验证 Worker 与 OceanBase 的连通性：

// 需要 mysql2 v3.13.0 或更高版本
import { createConnection } from "mysql2/promise";

export interface Env {
  HYPERDRIVE: {
    host: string;
    user: string;
    password: string;
    database: string;
    port: number;
  };
}

export default {
  async fetch(request: Request, env: Env, ctx: { waitUntil: (promise: Promise<any>) => void }): Promise<Response> {
    // 使用 mysql2 与 Hyperdrive 提供的凭据创建连接（仅从您的 Worker 内可访问）
    const connection = await createConnection({
      host: env.HYPERDRIVE.host,
      user: env.HYPERDRIVE.user,
      password: env.HYPERDRIVE.password,
      database: env.HYPERDRIVE.database,
      port: env.HYPERDRIVE.port,
      // 与 Workers 运行时兼容所需
      disableEval: true,
    });

    try {
      const [results, fields] = await connection.query("SHOW TABLES;");

      // 在响应返回后、Worker 终止前关闭连接
      ctx.waitUntil(connection.end());

      return Response.json({ results, fields });
    } catch (e) {
      console.error(e);
      return Response.json(
        { error: e instanceof Error ? e.message : "Unknown error" },
        { status: 500 }
      );
    }
  },
} satisfies ExportedHandler<Env>;

步骤六：部署并验证 Worker

部署 Worker

在项目根目录执行：

wrangler deploy

部署成功后，将得到 Worker 的访问地址（形如 https://oceanbase-tutorial.<您的子域名>）。

测试 Worker

使用 curl 发起 GET 请求，验证是否正常返回 OceanBase 的 SHOW TABLES 结果：

curl "https://oceanbase-tutorial.<您的子域名>"

若返回的 JSON 中包含 results 与 fields，且无报错，则说明 Worker 已成功连接 OB Cloud 云数据库。