PostgreSQLへの接続

HyperdriveはPostgreSQLおよびPostgreSQL互換のデータベース、サポートされているドライバーおよびそれらのドライバーを使用するオブジェクトリレーショナルマッパー（ORM）ライブラリをサポートしています。

Hyperdriveの作成

既存のPostgreSQLデータベースに接続するHyperdriveを作成するには、wrangler CLIまたはCloudflareダッシュボード ↗を使用します。

wranglerを使用する場合は、--connection-stringに提供されたプレースホルダー値をデータベースの接続文字列に置き換えます：

# wrangler v3.11以上が必要
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres://user:password@database.host.example.com:5432/databasenamehere"

上記のコマンドは、HyperdriveのIDを出力します。このIDは、Workersプロジェクトのwrangler.toml設定ファイルに設定する必要があります：

# データベースドライバーが機能するために必要
compatibility_flags = [ "nodejs_compat_v2" ]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

これにより、HyperdriveはWorker内で動的な接続文字列を生成し、既存のデータベースドライバーに渡すことができます。Hyperdriveでデータベースドライバーを設定する方法については、ドライバーの例を参照してください。

複数の人気データベースプロバイダーでHyperdriveを設定する方法については、例のドキュメントを参照してください。

サポートされているドライバー

HyperdriveはWorkersのTCPソケットサポートを使用して、データベースへのTCP接続をサポートします。以下の表は、サポートされているデータベースドライバーとHyperdriveで動作する最小バージョンを示しています：

ドライバー	ドキュメント	必要な最小バージョン	メモ
Postgres.js (推奨)	https://github.com/porsager/postgres ↗	`postgres@3.4.4`	WorkersおよびPagesの両方でサポートされています。
node-postgres - `pg`	https://node-postgres.com/ ↗	`pg@8.11.0`	`8.11.4`はURL解析にバグを導入し、動作しません。`8.11.5`で修正されました。`nodejs_compat_v2`互換フラグを設定する必要があります。
Drizzle	https://orm.drizzle.team/ ↗	`0.26.2`^
Kysely	https://kysely.dev/ ↗	`0.26.3`^

^ マークされたライブラリはnode-postgresを依存関係として使用しています。

リストに記載されていない他のドライバーやORMもサポートされている可能性があります：このリストは網羅的ではありません。

サポートされているTLS（SSL）モード

Hyperdriveは、オリジナルデータベースに接続する際に次のPostgreSQL TLS（SSL） ↗接続モードをサポートしています：

モード	サポートされている	詳細
`none`	いいえ	Hyperdriveは安全でないプレーンテキスト接続をサポートしていません。
`prefer`	いいえ（`require`を使用）	Hyperdriveは常にTLSを使用します。
`require`	はい（デフォルト）	TLSが必要であり、サーバー証明書が検証されます（WebPKIに基づく）。
`verify-ca`	現在ベータ版ではサポートされていません	サーバーのTLS証明書がクライアントのルートCAによって署名されていることを確認します。これにより、サーバーがクライアントが信頼する証明書を持っていることが保証されます。
`verify-full`	現在ベータ版ではサポートされていません	`verify-ca`と同じですが、データベースのホスト名が証明書に存在するサブジェクト代替名（SAN）と一致する必要があります。

ドライバーの例

以下の例では、次のことを示します：

データベースドライバーを使用してデータベースクライアントを作成します。
Hyperdrive接続文字列を渡してデータベースに接続します。
Hyperdriveを介してデータベースをクエリします。

Postgres.js

以下のWorkersコードは、HyperdriveでPostgres.js ↗を使用する方法を示しています。

Postgres.jsドライバーをインストールします：

npm install postgres

新しいsqlインスタンスを作成し、Hyperdriveパラメータを渡します：

postgres-js

import postgres from "postgres";

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

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // NOTE: 接続時に`prepare: false`が渡されると、パフォーマンスが
    // 遅くなりますが、正しくサポートされます。
    const sql = postgres(env.HYPERDRIVE.connectionString);

    try {
      // 非常にシンプルなテストクエリ
      const result = await sql`select * from pg_tables`;

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

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

node-postgres / pg

node-postgresドライバーをインストールします：

npm install pg

wrangler.toml設定ファイルの互換性フラグに”nodejs_compat_v2”が含まれていることを確認してください：

# 他のフィールドは省略
# node-postgresが動作するために必要
compatibility_flags = [ "nodejs_compat_v2"]

新しいClientインスタンスを作成し、Hyperdriveパラメータを渡します：

node-postgres

import { Client } from "pg";

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

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString,
    });

    try {
      // データベースに接続します
      await client.connect();

      // 非常にシンプルなテストクエリ
      const result = await client.query({ text: "SELECT * FROM pg_tables" });

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

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

Hyperdriveからの接続の識別

HyperdriveからPostgresデータベースサーバーへのアクティブな接続を識別するには：

Hyperdriveのデータベースへの接続は、pg_stat_activityテーブルのapplication_nameにCloudflare Hyperdriveとして表示されます。
SELECT DISTINCT usename, application_name FROM pg_stat_activity WHERE application_name = 'Cloudflare Hyperdrive'を実行して、Hyperdriveが現在データベースに接続を保持しているかどうかを確認します。

次のステップ

既存のデータベースに接続する他の方法を理解するために、サポートされているデータベース統合のリストを参照してください。
WorkerでソケットAPIを使用する方法について詳しく学びます。
Workersがサポートするプロトコルを理解します。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings