Merge branch 'cloudflare:production' into patch-prisma-postgres-guide

Author: ankur-arch

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

@@ -129,18 +129,14 @@ If successful, the command will output your new Hyperdrive configuration:
 
 ```json
 {
-	"id": "<example id: 57b7076f58be42419276f058a8968187>",
-	"name": "YOUR_CONFIG_NAME",
-	"origin": {
-		"host": "YOUR_DATABASE_HOST",
-		"port": 5432,
-		"database": "DATABASE",
-		"user": "DATABASE_USER"
-	},
-	"caching": {
-		"disabled": false
-	}
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+			"id": "<example id: 57b7076f58be42419276f058a8968187>"
+    }
+  ]
 }
+
 ```
 
 Copy the `id` field: you will use this in the next step to make Hyperdrive accessible from your Worker script.
@@ -151,6 +147,7 @@ Hyperdrive will attempt to connect to your database with the provided credential
 
 :::
 
+
 ## 4. Bind your Worker to Hyperdrive
 
 <Render file="create-hyperdrive-binding" product="hyperdrive" />

src/content/docs/hyperdrive/get-started.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

@@ -24,3 +24,24 @@ Specifically:
 - The value (string) you set for the `name` (binding name) will be used to reference this database in your Worker. In this tutorial, name your binding `HYPERDRIVE`.
 - The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "hyperdrive"` or `binding = "productionDB"` would both be valid names for the binding.
 - Your binding is available in your Worker at `env.<BINDING_NAME>`.
+
+
+If you wish to use a local database during development, you can add a `localConnectionString` to your  Hyperdrive configuration with the connection string of your database:
+
+
+<WranglerConfig>
+
+```toml
+[[hyperdrive]]
+binding = "HYPERDRIVE"
+id = "<YOUR_DATABASE_ID>" # the ID associated with the Hyperdrive you just created
+localConnectionString = "<LOCAL_DATABASE_CONNECTION_URI>"
+```
+
+</WranglerConfig>
+
+:::note
+
+Learn more about setting up [Hyperdrive for local development](/hyperdrive/configuration/local-development/).
+
+:::

src/content/partials/hyperdrive/create-hyperdrive-binding.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: |-

src/content/release-notes/hyperdrive.yaml

@@ -5,6 +5,10 @@ productLink: "/workers/"
 productArea: Developer platform
 productAreaLink: /workers/platform/changelog/platform/
 entries:
+  - publish_date: "2025-02-28"
+    description: |-
+      - Updated v8 to version 13.4.
+      - When using `nodejs_compat`, the new `nodejs_compat_populate_process_env` compatibility flag will cause `process.env` to be automatically populated with text bindings configured for the worker.
   - publish_date: "2025-02-26"
     description: |-
       - [Workers Builds](/workers/ci-cd/builds/) now supports building projects that use **pnpm 10** as the package manager. If your build previously failed due to this unsupported version, retry your build. No config changes needed.