ローカル開発

Hyperdrive は、Workers をローカルで開発・テストするときにも使えます。Workers のコマンドラインインターフェースである Wrangler には、ローカル開発用のオプションが 2 つあります。

• wrangler dev（デフォルト）: Worker のコードを自分のマシン上でローカル実行します。データベース（ローカルまたはリモート）に直接接続する localConnectionString を設定します。このモードでは Hyperdrive のクエリキャッシュは効きません。
• wrangler dev --remote: デプロイ済みの Hyperdrive 設定を使い、Worker を Cloudflare 上で実行します。Hyperdrive のコネクションプーリングとクエリキャッシュを有効にした状態でテストしたいときに使います。

デフォルトでは、wrangler dev は Worker のコードを自分のマシン上でローカル実行します。ローカル開発中にデータベースへ接続するには、データベースを直接指す localConnectionString を設定します。

localConnectionString は、ローカルデータベースとリモートデータベースの両方に使えます。

• ローカルデータベース: 自分のマシン上で動いているデータベースインスタンスに接続します（例: postgres://user:password@localhost:5432/database）
• リモートデータベース: TLS 経由でリモートデータベースに直接接続します（例: postgres://user:[email protected]:5432/database?sslmode=require または mysql://user:[email protected]:3306/database?sslMode=required）。必要な場合は SSL/TLS モードを指定してください。

認証情報をソース管理にコミットしないよう、環境変数を使う方法を推奨します。

# Your configured Hyperdrive binding is "HYPERDRIVE"
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"
npx wrangler dev

環境変数の形式は CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> です。<BINDING_NAME> は Wrangler 設定ファイル で Hyperdrive に割り当てたバインディング名です。

環境変数を解除するには: unset CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>

たとえば、ローカルデータベースの接続文字列を設定するには:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/databasename"
npx wrangler dev

または、Wrangler 設定ファイル に localConnectionString を設定できます。

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "c020574a-5623-407b-be0c-cd192bab9545",
			"localConnectionString": "postgres://user:password@localhost:5432/databasename"
		}
	]
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "c020574a-5623-407b-be0c-cd192bab9545"
localConnectionString = "postgres://user:password@localhost:5432/databasename"

環境変数と Wrangler 設定ファイルの localConnectionString の両方がある場合は、環境変数が優先されます。

wrangler dev --remote を実行すると、Worker は Cloudflare のネットワーク上で動き、デプロイ済みの Hyperdrive 設定を使います。つまり次のとおりです。

• Worker のコードはローカルではなく、Cloudflare の本番環境で実行されます
• Hyperdrive のコネクションプーリングとクエリキャッシュが有効になります
• wrangler hyperdrive create で作成した Hyperdrive 設定に指定したデータベースに接続します
• セッション中の変更はリモートリソースに影響します

このモードは、デプロイ前に Hyperdrive の機能を有効にした状態で Worker の動作を確認したいときに便利です。

wrangler.jsonc で Hyperdrive バインディングを設定します。

{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "your-hyperdrive-id",
		},
	],
}

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "your-hyperdrive-id"

リモート開発セッションを開始するには:

npx wrangler dev --remote

ローカル開発セッションの設定方法は、wrangler dev のドキュメント を参照してください。

• wrangler dev を使い、Worker と Hyperdrive をローカルで実行して、デプロイ前に問題をデバッグします。
• Hyperdrive の仕組み を確認します。
• Hyperdrive のクエリキャッシュ設定 を理解します。