add hyperdrive connection lifecycle docs (#26425)

* add hyperdrive connection lifecycle docs

* PCX Review

* Fixing missed link updates

* add nit to connection lifecycle garbage collection

---------

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

Author: 2 people

public/__redirects

@@ -2045,9 +2045,12 @@
 /version-management/reference/available-settings/ /version-management/reference/available-configurations/ 301
 
 # hyperdrive
-/hyperdrive/learning/how-hyperdrive-works/ /hyperdrive/configuration/how-hyperdrive-works/ 301
+/hyperdrive/configuration/how-hyperdrive-works/ /hyperdrive/concepts/how-hyperdrive-works/ 301
+/hyperdrive/configuration/query-caching/ /hyperdrive/concepts/query-caching/ 301
+/hyperdrive/configuration/connection-pooling/ /hyperdrive/concepts/connection-pooling/ 301
+/hyperdrive/learning/how-hyperdrive-works/ /hyperdrive/concepts/how-hyperdrive-works/ 301
 /hyperdrive/learning/connect-to-postgres/ /hyperdrive/examples/connect-to-postgres/ 301
-/hyperdrive/learning/query-caching/ /hyperdrive/configuration/query-caching/ 301
+/hyperdrive/learning/query-caching/ /hyperdrive/concepts/query-caching/ 301
 /hyperdrive/learning/troubleshooting/ /hyperdrive/observability/troubleshooting/ 301
 /hyperdrive/changelog/ /hyperdrive/platform/release-notes/ 301
 /hyperdrive/platform/changelog/ /hyperdrive/platform/release-notes/ 301

src/assets/images/hyperdrive/configuration/hyperdrive-connection-lifecycle.svg

@@ -18,4 +18,4 @@ _P50, P75, and P90 Hyperdrive session latency for all client connection sessions
 
 This performance improvement is applied to all new and existing Hyperdrive configurations that have caching enabled.
 
-For more details on how Hyperdrive performs query caching, refer to the [Hyperdrive documentation](/hyperdrive/configuration/how-hyperdrive-works/#query-caching).
+For more details on how Hyperdrive performs query caching, refer to the [Hyperdrive documentation](/hyperdrive/concepts/how-hyperdrive-works/#query-caching).

src/content/changelog/hyperdrive/2024-12-11-hyperdrive-caching-at-edge.mdx

@@ -14,6 +14,6 @@ By improving placement of Hyperdrive database connection pools, Workers' Smart P
 
 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/).
+Refer to [documentation on how Hyperdrive makes connecting to regional databases from Cloudflare Workers fast](/hyperdrive/concepts/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

@@ -46,4 +46,4 @@ export default {
 } satisfies ExportedHandler<Env>;
 ```
 
-Learn more about [how Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/) and [get started building Workers that connect to MySQL with Hyperdrive](/hyperdrive/get-started/).
+Learn more about [how Hyperdrive works](/hyperdrive/concepts/how-hyperdrive-works/) and [get started building Workers that connect to MySQL with Hyperdrive](/hyperdrive/get-started/).

src/content/changelog/hyperdrive/2025-04-08-hyperdrive-mysql-support.mdx

@@ -12,4 +12,4 @@ All configurations have a minimum of 5 connections. The maximum connection count
 
 This feature allows you to right-size your connection pool based on your database capacity and application requirements. You can configure connection counts through the Cloudflare dashboard or API.
 
-Refer to the [Hyperdrive configuration documentation](/hyperdrive/configuration/connection-pooling/) for more information.
+Refer to the [Hyperdrive configuration documentation](/hyperdrive/concepts/connection-pooling/) for more information.

src/content/changelog/hyperdrive/2025-07-02-hyperdrive-configurable-connection-count.mdx

@@ -0,0 +1,69 @@
+---
+pcx_content_type: concept
+title: Connection lifecycle
+sidebar:
+  order: 2
+---
+
+Understanding how connections work between Workers, Hyperdrive, and your origin database is essential for building efficient applications with Hyperdrive.
+
+By maintaining a connection pool to your database within Cloudflare's network, Hyperdrive reduces seven round-trips to your database before you can even send a query: the TCP handshake (1x), TLS negotiation (3x), and database authentication (3x).
+
+## How connections are managed
+
+When you use a database client in a Cloudflare Worker, the connection lifecycle works differently than in traditional server environments. Here's what happens:
+
+![Hyperdrive connection](~/assets/images/hyperdrive/configuration/hyperdrive-connection-lifecycle.svg)
+
+Without Hyperdrive, every Worker invocation would need to establish a new connection directly to your origin database. This connection setup process requires multiple roundtrips across the Internet to complete the TCP handshake, TLS negotiation, and database authentication — that's 7x round trips and added latency before your query can even execute.
+
+Hyperdrive solves this by splitting the connection setup into two parts: a fast edge connection and an optimized path to your database.
+
+1. **Connection setup on the edge**: The database driver in your Worker code establishes a connection to the Hyperdrive instance. This happens at the edge, colocated with your Worker, making it extremely fast to create connections. This is why you use Hyperdrive's special connection string.
+
+2. **Single roundtrip across regions**: Since authentication has already been completed at the edge, Hyperdrive only needs a single round trip across regions to your database, instead of the multiple roundtrips that would be incurred during connection setup.
+
+3. **Get existing connection from pool**: Hyperdrive uses an existing connection from the pool that is colocated close to your database, minimizing latency.
+
+4. **If no available connections, create new**: When needed, new connections are created from a region close to your database to reduce the latency of establishing new connections.
+
+5. **Run query**: Your query is executed against the database and results are returned to your Worker through Hyperdrive.
+
+6. **Connection teardown**: When your Worker finishes processing the request, the database client connection in your Worker is automatically garbage collected. However, Hyperdrive keeps the connection to your origin database open in the pool, ready to be reused by the next Worker invocation. This means subsequent requests will still perform the fast edge connection setup, but will reuse one of the existing connections from Hyperdrive's pool near your database.
+
+:::note
+
+In a Cloudflare Worker, database client connections within the Worker are only kept alive for the duration of a single invocation. With Hyperdrive, creating a new client on each invocation is fast and recommended because Hyperdrive maintains the underlying database connections for you, pooled in an optimal location and shared across Workers to maximize scale.
+
+:::
+
+## Connection lifecycle considerations
+
+### Durable Objects and persistent connections
+
+Unlike regular Workers, [Durable Objects](/durable-objects/) can maintain state across multiple requests. If you keep a database client open in a Durable Object, the connection will remain allocated from Hyperdrive's connection pool. Long-lived Durable Objects can exhaust available connections if many objects keep connections open simultaneously.
+
+:::caution
+
+Be careful when maintaining persistent database connections in Durable Objects. Each open connection consumes resources from Hyperdrive's connection pool, which could impact other parts of your application. Close connections when not actively in use, use connection timeouts, and limit the number of Durable Objects that maintain database connections.
+
+:::
+
+### Long-running transactions
+
+Hyperdrive operates in [transaction pooling mode](/hyperdrive/concepts/how-hyperdrive-works/#pooling-mode), where a connection is held for the duration of a transaction. Long-running transactions that contain multiple queries can exhaust Hyperdrive's available connections more quickly because each transaction holds a connection from the pool until it completes.
+
+:::tip
+
+Keep transactions as short as possible. Perform only the essential queries within a transaction, and avoid including non-database operations (like external API calls or complex computations) inside transaction blocks.
+
+:::
+
+Refer to [Limits](/hyperdrive/platform/limits/) to understand how many connections are available for your Hyperdrive configuration based on your Workers plan.
+
+## Related resources
+
+- [How Hyperdrive works](/hyperdrive/concepts/how-hyperdrive-works/)
+- [Connection pooling](/hyperdrive/concepts/connection-pooling/)
+- [Limits](/hyperdrive/platform/limits/)
+- [Durable Objects](/durable-objects/)

src/content/docs/hyperdrive/concepts/connection-lifecycle.mdx

@@ -2,9 +2,11 @@
 pcx_content_type: concept
 title: Connection pooling
 sidebar:
-  order: 5
+  order: 4
 ---
 
+import { Render } from "~/components";
+
 Hyperdrive maintains a pool of connections to your database. These are optimally placed to minimize the latency for your applications. You can configure
 the amount of connections your Hyperdrive configuration uses to connect to your origin database. This enables you to right-size your connection pool based on your database capacity and application requirements.
 
@@ -19,6 +21,10 @@ Hyperdrive will automatically scale the amount of database connections held open
 
 The `max_size` parameter acts as a soft limit - Hyperdrive may temporarily create additional connections during network issues or high traffic periods to ensure high availability and resiliency.
 
+## Pooling mode
+
+<Render file="pooling-mode" product="hyperdrive" />
+
 ## Best practices
 
 You can configure connection counts using the Cloudflare dashboard or the Cloudflare API. Consider the following best practices to determine the right limit for your use-case:
@@ -30,6 +36,6 @@ You can configure connection counts using the Cloudflare dashboard or the Cloudf
 
 ## Next steps
 
-- Learn more about [How Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).
+- Learn more about [How Hyperdrive works](/hyperdrive/concepts/how-hyperdrive-works/).
 - Review [Hyperdrive limits](/hyperdrive/platform/limits/) for your Workers plan.
 - Learn how to [Connect to PostgreSQL](/hyperdrive/examples/connect-to-postgres/) from Hyperdrive.

src/content/docs/hyperdrive/configuration/connection-pooling.mdx renamed to src/content/docs/hyperdrive/concepts/connection-pooling.mdx

@@ -2,12 +2,14 @@
 pcx_content_type: concept
 title: How Hyperdrive works
 sidebar:
-  order: 2
+  order: 1
 ---
 
+import { Render } from "~/components";
+
 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.
 
-If your database is centrally located, queries can take a long time to get to the database and back. Queries can take even longer in situations where you have to establish a connection and make multiple round trips.
+If your database is centrally located, queries can take a long time to get to the database and back. Queries can take even longer in situations where you have to establish new connections from stateless environments like Workers, requiring multiple round trips for each Worker invocation.
 
 Traditional databases usually handle a maximum number of connections. With any reasonably large amount of distributed traffic, it becomes easy to exhaust these connections.
 
@@ -31,6 +33,8 @@ When a database driver connects to a database from a Cloudflare Worker **directl
 
 **With Hyperdrive**, this connection setup occurs between your Cloudflare Worker and Hyperdrive on the edge, as close to your Worker as possible (see diagram, label _1. Connection setup_). This incurs significantly less latency, since the connection setup is completed within the same location.
 
+Learn more about how connections work between Workers and Hyperdrive in [Connection lifecycle](/hyperdrive/concepts/connection-lifecycle/).
+
 ### 2. Connection Pooling
 
 Hyperdrive creates a pool of connections to your database that can be reused as your application executes queries against your database.
@@ -45,6 +49,8 @@ If the connection pool does not have pre-existing connections, it will establish
 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.
 :::
 
+Learn more about connection pooling behavior and configuration in [Connection pooling](/hyperdrive/concepts/connection-pooling/).
+
 ### 3. Query Caching
 
 Hyperdrive supports caching of non-mutating (read) queries to your database.
@@ -55,16 +61,14 @@ For non-mutating queries, Hyperdrive will cache the response for the configured
 
 Caching reduces the burden on your origin database and accelerates the response times for your queries.
 
-## Pooling mode
+Learn more about query caching behavior and configuration in [Query caching](/hyperdrive/concepts/query-caching/).
 
-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.
-
-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.
+## Pooling mode
 
-Hyperdrive supports named prepared statements as implemented in the `postgres.js` and `node-postgres` drivers. Named prepared statements in other drivers may have worse performance or may not be supported.
+<Render file="pooling-mode" product="hyperdrive" />
 
 ## Related resources
 
-- [Query caching](/hyperdrive/configuration/query-caching/)
+- [Connection lifecycle](/hyperdrive/concepts/connection-lifecycle/)
+- [Query caching](/hyperdrive/concepts/query-caching/)
+- [Connection pooling](/hyperdrive/concepts/connection-pooling/)

src/content/docs/hyperdrive/configuration/how-hyperdrive-works.mdx renamed to src/content/docs/hyperdrive/concepts/how-hyperdrive-works.mdx

@@ -0,0 +1,10 @@
+---
+pcx_content_type: navigation
+title: Concepts
+sidebar:
+  order: 3
+  group:
+    hideIndex: true
+---
+
+Learn about the core concepts and architecture behind Hyperdrive.