Hyperdrive は、データベースへの接続プールを維持します。プールは、アプリケーションのレイテンシを抑える位置に置かれます。オリジンデータベースへの接続数は、Hyperdrive の設定で変えられます。データベースの容量とアプリケーションの要件に合わせて、接続プールのサイズを調整できます。
たとえば、Worker がデータベースへ多くのクエリを送る場合（Hyperdrive のキャッシュでは解決できない場合）は、Hyperdrive がデータベースへ張る接続数を増やせます。 逆に、データベースまで届くクエリが少ない場合や、データベースが許可する接続数が少ない場合は、Hyperdrive が張る接続数を減らせます。
すべての設定で接続数の下限は 5 です。上限は Workers プランによって異なります。詳細は 制限 を参照してください。
Hyperdrive は、トラフィックとデータベースへの負荷に応じて、開いておくデータベース接続の数を自動でスケールします。
max_size パラメーターは目安の上限です。ネットワーク障害や高トラフィック時には、可用性と耐障害性を確保するため、Hyperdrive が一時的に追加の接続を作ることがあります。
Hyperdrive は接続プールを管理します。ほとんどのデータベースフェイルオーバーは自動で検出し、復旧します。まれに、緊急対応としてプールを手動で再起動する必要があります。たとえば、データベースのフェイルオーバー後に、Hyperdrive がまだ新しいプライマリへ接続を切り替えていない場合です。
再起動するには、Cloudflare ダッシュボードで Hyperdrive の設定を選び、Settings タブを開き、Danger zone の Restart を選びます。再起動には Hyperdrive Admin ロール が必要です。
再起動すると、既存の接続プールを空にし、オリジンデータベースへ新しい接続を張らせます。再起動後、Settings タブに、設定を最後に手動再起動した時刻が表示されます。
Hyperdrive のコネクションプーラーはトランザクションモードで動作します。クエリを実行するクライアントは、トランザクションのあいだ 1 本の接続を通じて通信します。トランザクションが完了すると、その接続はプールに戻されます。
Hyperdrive は、トランザクションまたはクエリのあいだ SET ステートメント ↗ に対応します。たとえば、BEGIN / COMMIT で手動でトランザクションを作った場合、そのトランザクション内の SET ステートメントは有効になります。また、SET コマンドを含むクエリ（SET X; SELECT foo FROM bar;）でも SET コマンドが適用されます。接続がプールに戻されると、接続は RESET されるため、その後のクエリには SET コマンドは効きません。
そのため、1 回の Worker 呼び出しでデータベース操作のために複数の接続を取得することがあり、クエリまたはトランザクションごとに設定を SET し直す必要がある場合があります。SET の状態を保つために複数のデータベース操作を 1 つのトランザクションでまとめることはおすすめしません。そのあいだ接続をほかの Worker isolate が再利用できないため、Hyperdrive の性能とスケールに影響します。
Hyperdrive は、postgres.js および node-postgres ドライバーで実装されている名前付きプリペアドステートメントに対応します。ほかのドライバーの名前付きプリペアドステートメントは、性能が落ちるか、未対応のことがあります。
接続数は、Cloudflare ダッシュボードまたは Cloudflare API で設定できます。上限を決めるときは、次のベストプラクティスを検討してください。
- 控えめに始める: まず少なめの接続数から始め、アプリケーションの性能を見ながら増やします。
- データベースのメトリクスを監視する: データベースの接続使用量と性能メトリクスを見て、接続数を最適化します。
- データベースの上限を考慮する: 設定した接続数が、データベースの最大接続数を超えないようにします。
- 複数設定を合算する: 同じデータベースに複数の Hyperdrive 設定が接続している場合は、全設定の接続数の合計を考慮します。
- Hyperdrive の仕組み を確認します。
- Workers プランの Hyperdrive の制限 を確認します。
- Hyperdrive から PostgreSQL に接続する 方法を確認します。