Cloudflare WorkersでOceanBase Cloudに接続する

Cloudflare Workersは、特定のイベントが発生したときにエッジノード上でコードを実行できる機能であり、カスタムAPI、サーバーレス関数、マイクロサービスの構築に適しており、低遅延や弾力的なスケーリングが求められるシナリオに特に有効です。OceanBase CloudはMySQLプロトコルに対応しており、TCPとHyperdriveを介してCloudflare Workersと接続を確立できます。

本記事では、Cloudflare Workersアプリケーションを作成し、OceanBase Cloudに接続して、データベース内のデータとやり取りする方法について説明します。

前提条件

• OceanBase Cloudデータベースアカウントに登録済みであり、トランザクション型インスタンスとMySQL互換モードのテナントを作成していること。詳細については、クラスタインスタンスの作成およびテナントの作成をご参照ください。
• データベースとアカウントが作成済みであり、アカウントに読み書き権限が付与されていること。詳細については、アカウントの作成およびデータベースの作成(MySQL専用)をご参照ください。
• プロジェクト管理者またはインスタンス管理者ロールを持ち、プロジェクト内のインスタンスに対する読み書き操作が可能であること。権限がない場合は、組織管理者に連絡し追加してもらってください。
• Cloudflareアカウントに登録済みであること。
• Node.jsがインストール済みで、バージョンが16.17.0以上であること(Wrangler CLIはこのバージョンに依存しています)。

ステップ1：データベース接続情報を取得する

1. OceanBase Cloudコンソールにログインします。インスタンスリストページで、対象のトランザクション型インスタンスの情報を展開し、対象のテナントで、接続 > 接続文字列を取得する をクリックします。

2. ポップアップウィンドウで、パブリックネットワーク接続 を選択します。

3. パブリックネットワーク経由で接続 ページで以下の設定を完了し、接続文字列を生成します：

   1. (オプション) テナントに既に生成されたパブリックアドレスがない場合、ステップ1: パブリックアドレスを取得する の下で、パブリックエンドポイントを取得 をクリックしてパブリックアドレスを取得します。既にパブリックアドレスがある場合は、この手順をスキップしてください。アドレスが生成されたら、次へ をクリックします。

   2. ステップ2: セキュリティ設定 で、以下の設定を完了した後、次へ をクリックします：

      • IPアドレスを許可リストに追加：追加 をクリックし、すべてのIPアドレスからのアクセスを許可 を選択します(WorkersはCloudflareエッジで実行されるため、アクセスを許可する必要があります)。その後、OK をクリックします。

      • 証明書のダウンロード：CA証明書をダウンロード をクリックして証明書をダウンロードし、認証を完了します。

   3. ステップ3: データベースへのアクセス で、前提条件で作成したデータベースとアカウントを選択し、接続方法として MySQL CLI を選択します。完了後、接続文字列をコピーし、後のHyperdriveとDATABASE_URLの設定に使用します。

ステップ2：Wranglerのインストールと設定

Wranglerは、Cloudflareが公式に提供するWorkersコマンドラインツールであり、Workersの作成、ビルド、プレビュー、デプロイに使用されます。

Wranglerのインストール

npm install -g wrangler

環境変数の設定

1. Cloudflareコンソールで APIトークンの作成：

   1. Create Token をクリックします。
   2. Edit Cloudflare Workers テンプレートを選択し、Hyperdrive権限を追加します。
   3. 生成されたAPIトークンをコピーします。
   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
   

ステップ3：DATABASE_URL秘密鍵を設定する

DATABASE_URL の形式は次のとおりです：mysql://ユーザー名:パスワード@ホスト:ポート/データベース名。ステップ1 でコピーした接続情報を使用してこの形式に組み立ててください。

プロジェクトのルートディレクトリで実行します：

wrangler secret put DATABASE_URL

プロンプトに従って、DATABASE_URL を入力します。設定が成功すると、次のようなメッセージが表示されます：

✨ Success! Uploaded secret DATABASE_URL

ステップ4：Hyperdriveを作成し、Workerにバインドする

Hyperdrive設定の作成

OceanBase 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 を ステップ1 で取得した実際の接続情報に置き換えてください。コマンドを実行すると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"
  

ステップ5：依存関係のインストールと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との接続性を検証するために簡単なクエリを1回実行します。

// 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>;

ステップ6：Workerのデプロイと検証

Workerのデプロイ

プロジェクトのルートディレクトリで次のコマンドを実行します：

wrangler deploy

デプロイが成功すると、Workerのアクセスアドレス（例：https://oceanbase-tutorial. ` の形式）が取得されます。

Workerのテスト

curl を使用してGETリクエストを送信し、OceanBaseの SHOW TABLES 結果が正常に返されるか確認します：

curl "https://oceanbase-tutorial.<your-subdomain>"

返されたJSONに results と fields が含まれ、エラーがなければ、WorkerはOceanBase Cloudに正常に接続されています。