コンテンツにスキップ

始める

Hyperdriveは、Cloudflare Workersから既存のデータベースへのアクセスを加速し、単一リージョンのデータベースでさえもグローバルに分散されているように感じさせます。

Cloudflareのネットワーク内でデータベースへの接続プールを維持することで、Hyperdriveはクエリを送信する前にデータベースへの7回の往復を削減します：TCPハンドシェイク（1回）、TLSネゴシエーション（3回）、およびデータベース認証（3回）です。

Hyperdriveは、データベースへの読み取りクエリと書き込みクエリの違いを理解し、最も一般的な読み取りクエリをキャッシュすることで、パフォーマンスを向上させ、オリジナルのデータベースへの負荷を軽減します。

このガイドでは、以下の手順を説明します：

  • 最初のHyperdrive構成を作成する。
  • Cloudflare Workerを作成し、それをHyperdrive構成にバインドする。
  • Workerから公開データベースへのデータベース接続を確立する。

前提条件

続行するには、以下が必要です：

  1. まだ持っていない場合は、Cloudflareアカウント ↗を作成してください。
  2. ローカルマシンにnpm ↗をインストールしてください。
  3. Node.js ↗をインストールしてください。権限の問題を避け、Node.jsのバージョンを変更するために、Volta ↗やnvm ↗のようなNodeバージョンマネージャーを使用してください。Wranglerは、16.17.0以上のNodeバージョンを必要とします。
  4. 公開アクセス可能なPostgreSQL（またはPostgreSQL互換）データベース。既存のデータベースがない場合は、CloudflareはNeon ↗を推奨します。最初のデータベースを作成するためのNeonドキュメントを読む ↗。

1. ログイン

Hyperdriveバインディングを作成する前に、次のコマンドを実行してCloudflareアカウントでログインします：

Terminal window
npx wrangler login

Cloudflareダッシュボードにログインするように求められるウェブページにリダイレクトされます。ログインした後、WranglerがCloudflareアカウントに変更を加えることができるかどうか尋ねられます。下にスクロールして許可を選択して続行します。

2. Workerを作成する

次のコマンドを実行して、hyperdrive-tutorialという新しいプロジェクトを作成します：

Terminal window
npm create cloudflare@latest -- hyperdrive-tutorial

For setup, select the following options:

  • For What would you like to start with?, choose Hello Worldの例.
  • For Which template would you like to use?, choose Hello World Worker.
  • For Which language do you want to use?, choose TypeScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

これにより、新しいhyperdrive-tutorialディレクトリが作成されます。新しいhyperdrive-tutorialディレクトリには以下が含まれます：

  • src/index.tsにある「Hello World」Worker。
  • wrangler.toml構成ファイル。wrangler.tomlは、hyperdrive-tutorial WorkerがHyperdriveに接続する方法です。

3. Hyperdriveをデータベースに接続する

Hyperdriveは、データベースに接続することで機能します。

最初のHyperdriveデータベース構成を作成するには、Workersプロジェクトのために作成したディレクトリに移動します：

Terminal window
cd hyperdrive-tutorial

最初のHyperdriveを作成するには、以下が必要です：

  • データベースのIPアドレス（またはホスト名）とポート。
  • データベースのユーザー名（例：hyperdrive-demo）。
  • そのユーザー名に関連付けられたパスワード。
  • Hyperdriveが接続するデータベースの名前。例えば、postgres。

Hyperdriveは、データベースドライバーで使用される一般的な接続文字列形式でこれらのパラメータの組み合わせを受け入れます：

postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

ほとんどのデータベースプロバイダーは、Hyperdriveに直接コピー＆ペーストできる接続文字列を提供します。

Hyperdrive接続を作成するには、次のwranglerコマンドを実行し、--connection-stringフラグに渡されるプレースホルダー値を既存のデータベースの値に置き換えます：

Terminal window
npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"

成功すると、コマンドは新しいHyperdrive構成を出力します：

{
  "id": "<example id: 57b7076f58be42419276f058a8968187>",
  "name": "YOUR_CONFIG_NAME",
  "origin": {
    "host": "YOUR_DATABASE_HOST",
    "port": 5432,
    "database": "DATABASE",
    "user": "DATABASE_USER"
  },
  "caching": {
    "disabled": false
  }
}

idフィールドをコピーしてください：次のステップでWorkerスクリプトからHyperdriveにアクセスできるように使用します。

4. WorkerをHyperdriveにバインドする

WorkerがHyperdrive構成に接続するためのバインディングを作成する必要があります。Bindingsを使用すると、Cloudflare開発者プラットフォーム上のD1などのリソースにWorkersがアクセスできます。wrangler.tomlファイルを更新することでバインディングを作成します。

Hyperdrive構成をWorkerにバインドするには、wrangler.tomlファイルの末尾に以下を追加します：

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>" # 先ほど作成したHyperdriveに関連付けられたID

具体的には：

  • name（バインディング名）に設定する値（文字列）は、Worker内でこのデータベースを参照するために使用されます。このチュートリアルでは、バインディングの名前をHYPERDRIVEとします。
  • バインディングは有効なJavaScript変数名 ↗でなければなりません。例えば、binding = "hyperdrive"やbinding = "productionDB"は、どちらもバインディングの有効な名前です。
  • バインディングは、Worker内でenv.<BINDING_NAME>として利用可能です。

5. データベースに対してクエリを実行する

データベースドライバーをインストールする

データベースに接続するには、データベースを認証し、クエリを実行するためのデータベースドライバーが必要です。このチュートリアルでは、最も広く使用されているPostgreSQLドライバーの1つであるPostgres.js ↗を使用します。

postgresをインストールするには、hyperdrive-tutorialディレクトリにいることを確認してください。ターミナルを開き、次のコマンドを実行します：

Terminal window
# これによりv3.4.4以上がインストールされるはずです
npm i postgres

ドライバーがインストールされたので、データベースをクエリするWorkerスクリプトを作成できます。

Workerを書く

データベースを設定したら、Worker内からSQLクエリを実行します。

hyperdrive-tutorial Workerに移動し、index.tsファイルを開きます。

index.tsファイルは、WorkerのHyperdriveとのインタラクションを構成する場所です。

次のコードでindex.tsファイルを埋めます：

// Postgres.js 3.4.4以上を推奨
import postgres from "postgres";


export interface Env {
  // wrangler.tomlで'binding'の値に別の名前を設定した場合は、
  // "HYPERDRIVE"を定義した変数名に置き換えてください。
  HYPERDRIVE: Hyperdrive;
}


export default {
  async fetch(request, env, ctx): Promise<Response> {
    console.log(JSON.stringify(env));
    // Hyperdrive経由でデータベースに接続するデータベースクライアントを作成します。
    //
    // Hyperdriveは、node-postgres、Postgres.js、これらのドライバーを使用する多くのORMやクエリビルダーを含む
    // サポートされているドライバーに渡すことができるユニークな接続文字列を生成します。
    const sql = postgres(env.HYPERDRIVE.connectionString);


    try {
      // テストクエリ
      const results = await sql`SELECT * FROM pg_tables`;


      // クライアントをクリーンアップし、完了する前にWorkerを終了しないようにします。
      ctx.waitUntil(sql.end());


      // 結果行をJSONとして返します
      return Response.json(results);
    } catch (e) {
      console.error(e);
      return Response.json(
        { error: e instanceof Error ? e.message : e },
        { status: 500 },
      );
    }
  },
} satisfies ExportedHandler<Env>;

リクエストを受け取ると、上記のコードは以下のことを行います：

  1. Hyperdrive接続文字列を使用して、データベースに接続するように構成された新しいデータベースクライアントを作成します。
  2. await sqlを介してクエリを開始し、データベース内のすべてのテーブル（ユーザーおよびシステム作成）を出力します（例のクエリとして）。
  3. クライアントにJSONとして応答を返します。

6. Workerをデプロイする

これで、Workerをデプロイしてプロジェクトをインターネット上でアクセス可能にできます。Workerをデプロイするには、次のコマンドを実行します：

Terminal window
npx wrangler deploy
# 出力: https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev

新しく作成したプロジェクトのURLにアクセスして、ライブデータベースをクエリできます。

例えば、新しいWorkerのURLがhyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.devの場合、https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev/にアクセスすると、データベースを直接クエリするWorkerにリクエストが送信されます。

このチュートリアルを完了することで、Hyperdrive構成、データベースにアクセスするWorker、およびプロジェクトをグローバルにデプロイしました。

次のステップ

機能リクエストがある場合やバグに気付いた場合は、DiscordのCloudflare Developersコミュニティ ↗に参加して、Cloudflareチームに直接フィードバックを共有してください。

Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings