[Hyperdrive] Hyperdrive pool placement improvement + ip address egress (#20239)

* thomasgauvin: Hyperdrive pool placement improvement + ip address egress

* thomasgauvin: add details to how hyperdrive works with changes

* Update src/content/changelog/hyperdrive/2025-02-26-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

* thomasgauvin: add docs on networking, firewall and ip addresses

* small changes to phrasing, update date, include screenshot

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

Co-authored-by: Jun Lee <[email protected]>

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

Co-authored-by: Jun Lee <[email protected]>

* Update src/content/release-notes/hyperdrive.yaml

Co-authored-by: Jun Lee <[email protected]>

* Update src/content/docs/hyperdrive/reference/faq.mdx

Co-authored-by: Jun Lee <[email protected]>

* Update src/content/docs/hyperdrive/configuration/how-hyperdrive-works.mdx

Co-authored-by: Jun Lee <[email protected]>

* Update src/content/release-notes/hyperdrive.yaml

Co-authored-by: Jun Lee <[email protected]>

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

* Update src/content/release-notes/hyperdrive.yaml

* Update src/content/release-notes/hyperdrive.yaml

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

Co-authored-by: Matt Silverlock <[email protected]>

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

Co-authored-by: Matt Silverlock <[email protected]>

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

Co-authored-by: Matt Silverlock <[email protected]>

* Update src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

* Update src/content/docs/hyperdrive/configuration/firewall-and-networking-configuration.mdx

---------

Co-authored-by: Jun Lee <[email protected]>
Co-authored-by: Matt Silverlock <[email protected]>

Author: 3 people

src/assets/images/hyperdrive/configuration/hyperdrive-regional-pooling-query-latency-improvement.png

@@ -0,0 +1,19 @@
+---
+title: Hyperdrive reduces query latency by up to 90% and now supports IP access control lists
+description: Hyperdrive now pools database connections closer to your database to reduce query latency, and now also provides a documented IP address range for IP ACLs.
+products:
+  - hyperdrive
+date: 2025-03-07T18:00:00Z
+---
+
+Hyperdrive now pools database connections in one or more regions close to your database. This means that your uncached queries and new database connections have up to 90% less latency as measured from connection pools.
+
+![Hyperdrive query latency decreases by 90% during Hyperdrive's gradual rollout of regional pooling.](~/assets/images/hyperdrive/configuration/hyperdrive-regional-pooling-query-latency-improvement.png)
+
+By improving placement of Hyperdrive database connection pools, Workers' Smart Placement is now more effective when used with Hyperdrive, ensuring that your Worker can be placed as close to your database as possible.
+
+With this update, Hyperdrive also uses [Cloudflare's standard IP address ranges](https://www.cloudflare.com/ips/) to connect to your database. This enables you to configure the firewall policies (IP access control lists) of your database to only allow access from Cloudflare and Hyperdrive.
+
+Refer to [documentation on how Hyperdrive makes connecting to regional databases from Cloudflare Workers fast](/hyperdrive/configuration/how-hyperdrive-works/).
+
+This improvement is enabled on all Hyperdrive configurations.

src/content/changelog/hyperdrive/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress.mdx

@@ -0,0 +1,16 @@
+---
+pcx_content_type: concept
+title: Firewall and networking configuration
+sidebar:
+  order: 7
+---
+
+import { TabItem, Tabs, Render, WranglerConfig } from "~/components";
+
+Hyperdrive uses the [Cloudflare IP address ranges](https://www.cloudflare.com/ips/) to connect to your database. If you decide to restrict the IP addresses that can access your database with firewall rules, the IP address ranges listed in this reference need to be allow-listed in your database's firewall and networking configurations.
+
+You can connect to your database from Hyperdrive using any of the 3 following networking configurations:
+
+1. Configure your database to allow inbound connectivity from the public Internet (all IP address ranges).
+2. Configure your database to allow inbound connectivity from the public Internet, with only the IP address ranges used by Hyperdrive allow-listed in an IP access control list (ACL).
+3. Configure your database to allow inbound connectivity from a private network, and run a Cloudflare Tunnel instance in your private network to enable Hyperdrive to connect from the Cloudflare network to your private network. Refer to [documentation on connecting to a private database using Tunnel](/hyperdrive/configuration/connect-to-private-database/).

src/content/docs/hyperdrive/configuration/firewall-and-networking-configuration.mdx

@@ -3,7 +3,6 @@ pcx_content_type: concept
 title: How Hyperdrive works
 sidebar:
   order: 2
-
 ---
 
 Connecting to traditional centralized databases from Cloudflare's global network which consists of over [300 data center locations](https://www.cloudflare.com/network/) presents a few challenges as queries can originate from any of these locations.
@@ -16,9 +15,17 @@ Hyperdrive solves these challenges by managing the number of global connections
 
 ![Hyperdrive connection](~/assets/images/hyperdrive/configuration/hyperdrive-comparison.svg)
 
+## Edge connection setup
+
+When a database driver connects to a database from a Cloudflare Worker (illustrated above on the right half of the diagram in **Direct (without Hyperdrive)**) it will first go through the connection setup. This may require multiple round trips to the database in order to verify and establish a secure connection. This can incur additional network latency due to the distance between your Cloudflare Worker and your database.
+
+**With Hyperdrive** (on the left half of the above diagram), this connection setup occurs between your Cloudflare Worker and Hyperdrive on the edge, as close to your Worker as possible. This incurs significantly less latency, since the connection setup is completed within the same location.
+
 ## Connection Pooling
 
-Hyperdrive creates a global pool of connections to your database that can be reused as your application executes queries against your database.
+Hyperdrive creates a pool of connections to your database that can be reused as your application executes queries against your database.
+
+The pool of database connections is placed in one or more regions closest to your origin database. This minimizes the latency incurred by roundtrips between your Cloudflare Workers and database to establish new connections. This also ensures that as little network latency is incurred for uncached queries.
 
 When a query hits Hyperdrive, the request is routed to the nearest connection pool.
 
@@ -28,15 +35,14 @@ If the connection pool does not have pre-existing connections, it will establish
 
 :::note
 
-Hyperdrive automatically manages the connection pool properties for you, including limiting the total number of connections to your origin database. Refer to [Limits](/hyperdrive/platform/limits/) to learn more. 
+Hyperdrive automatically manages the connection pool properties for you, including limiting the total number of connections to your origin database. Refer to [Limits](/hyperdrive/platform/limits/) to learn more.
 :::
 
 ## Pooling mode
 
 The Hyperdrive connection pooler operates in transaction mode, where the client that executes the query communicates through a single connection for the duration of a transaction. When that transaction has completed, the connection is returned to the pool.
 
-
-Hyperdrive supports [`SET` statements](https://www.postgresql.org/docs/current/sql-set.html) for the duration of a transaction or a query. For instance, if you manually create a transaction with `BEGIN`/`COMMIT`, `SET` statements within the transaction will take effect. Moreover, a query that includes a `SET` command (`SET X; SELECT foo FROM bar;`) will also apply the `SET` command. When a connection is returned to the pool, the connection is `RESET` such that the `SET` commands will not take effect on subsequent queries. 
+Hyperdrive supports [`SET` statements](https://www.postgresql.org/docs/current/sql-set.html) for the duration of a transaction or a query. For instance, if you manually create a transaction with `BEGIN`/`COMMIT`, `SET` statements within the transaction will take effect. Moreover, a query that includes a `SET` command (`SET X; SELECT foo FROM bar;`) will also apply the `SET` command. When a connection is returned to the pool, the connection is `RESET` such that the `SET` commands will not take effect on subsequent queries.
 
 This implies that a single Worker invocation may obtain multiple connections to perform its database operations and may need to `SET` any configurations for every query or transaction. It is not recommended to wrap multiple database operations with a single transaction to maintain the `SET` state. Doing so will affect the performance and scaling of Hyperdrive as the connection cannot be reused by other Worker isolates for the duration of the transaction.
 
@@ -46,11 +52,11 @@ Hyperdrive supports named prepared statements as implemented in the `postgres.js
 
 Hyperdrive does not support the following PostgreSQL features:
 
-* SQL-level management of prepared statements, such as using `PREPARE`, `DISCARD`, `DEALLOCATE`, or `EXECUTE`.
-* Advisory locks ([PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)).
-* `LISTEN` and `NOTIFY`.
-* `PREPARE` and `DEALLOCATE`.
-* Any modification to per-session state not explicitly documented as supported elsewhere.
+- SQL-level management of prepared statements, such as using `PREPARE`, `DISCARD`, `DEALLOCATE`, or `EXECUTE`.
+- Advisory locks ([PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)).
+- `LISTEN` and `NOTIFY`.
+- `PREPARE` and `DEALLOCATE`.
+- Any modification to per-session state not explicitly documented as supported elsewhere.
 
 In cases where you need to issue these unsupported statements from your application, the Hyperdrive team recommends setting up a second, direct client without Hyperdrive.
 
@@ -66,4 +72,4 @@ Caching reduces the burden on your origin database and accelerates the response
 
 ## Related resources
 
-* [Query caching](/hyperdrive/configuration/query-caching/)
+- [Query caching](/hyperdrive/configuration/query-caching/)

src/content/docs/hyperdrive/configuration/how-hyperdrive-works.mdx

@@ -3,11 +3,18 @@ pcx_content_type: concept
 title: FAQ
 sidebar:
   order: 10
-
 ---
 
 Below you will find answers to our most commonly asked questions regarding Hyperdrive.
 
+## Connectivity
+
+### Does Hyperdrive use specific IP addresses to connect to my database?
+
+Hyperdrive connects to your database using [Cloudflare's IP address ranges](https://www.cloudflare.com/ips/). These are shared by all Hyperdrive configurations and other Cloudflare products.
+
+You can use this to configure restrictions in your database firewall to restrict the IP addresses that can access your database.
+
 ## Pricing
 
 ### Does Hyperdrive charge for data transfer / egress?
@@ -27,4 +34,3 @@ Hyperdrive itself does not charge for compute (CPU) or processing (wall clock) t
 ### Are there any limits to Hyperdrive?
 
 Refer to the published [limits](/hyperdrive/platform/limits/) documentation.
-

src/content/docs/hyperdrive/reference/faq.mdx

@@ -5,6 +5,22 @@ productLink: "/hyperdrive/"
 productArea: Developer platform
 productAreaLink: /workers/platform/changelog/platform/
 entries:
+  - publish_date: "2025-03-07"
+    title: Hyperdrive connects to your database using Cloudflare's IP address ranges
+    description: |-
+      Hyperdrive now uses [Cloudflare's IP address ranges]((https://www.cloudflare.com/ips/) for egress. 
+
+      This enables you to configure the firewall policies on your database to allow access to this limited IP address range. 
+
+      Learn more about [configuring your database networking for Hyperdrive](/hyperdrive/configuration/firewall-and-networking-configuration/).
+  - publish_date: "2025-03-07"
+    title: Hyperdrive improves connection pool placement, decreasing query latency by up to 90%
+    description: |-
+      Hyperdrive now pools all database connections in one or more regions as close to your database as possible. This means that your uncached queries and new database connections have up to 90% less latency as measured from Hyperdrive connection pools.
+
+      With improved placement for Hyperdrive connection pools, Workers' Smart Placement is more effective by ensuring that your Worker and Hyperdrive database connection pool are placed as close to your database as possible.
+
+      See [the announcement](/changelog/2025-03-04-hyperdrive-pooling-near-database-and-ip-range-egress/) for more details.
   - publish_date: "2025-01-28"
     title: Hyperdrive automatically configures your Cloudflare Tunnel to connect to your private database.
     description: |-