diff --git a/src/content/changelog/hyperdrive/2026-09-10-hyperdrive-paid-connection-limit.mdx b/src/content/changelog/hyperdrive/2026-09-10-hyperdrive-paid-connection-limit.mdx new file mode 100644 index 00000000000..36af8f6b3d8 --- /dev/null +++ b/src/content/changelog/hyperdrive/2026-09-10-hyperdrive-paid-connection-limit.mdx @@ -0,0 +1,15 @@ +--- +title: Hyperdrive raises Workers Paid connection limit +description: Customers on a Workers Paid plan can configure up to 1,500 origin connections per Hyperdrive configuration. +products: + - hyperdrive +date: 2026-09-10 +--- + +Customers on a Workers Paid plan can configure up to 1,500 origin database connections per Hyperdrive configuration. This increases the connection pool size available for workloads that need more concurrent database access. + +The origin connection limit is the maximum number of database connections that Hyperdrive can make to your origin database. You can configure this value in the dashboard settings for your Hyperdrive configuration. + +Set this value lower than your origin database's own connection limit to leave room for adjustments. + +For more information, refer to [Hyperdrive limits](/hyperdrive/platform/limits/) and [Tune connection pooling](/hyperdrive/configuration/tune-connection-pool/). diff --git a/src/content/docs/hyperdrive/concepts/connection-pooling.mdx b/src/content/docs/hyperdrive/concepts/connection-pooling.mdx index a98e38f73cd..3b84947eacc 100644 --- a/src/content/docs/hyperdrive/concepts/connection-pooling.mdx +++ b/src/content/docs/hyperdrive/concepts/connection-pooling.mdx @@ -16,13 +16,15 @@ the amount of connections your Hyperdrive configuration uses to connect to your For instance, if your Worker makes many queries to your database (which cannot be resolved by Hyperdrive's caching), you may want to allow Hyperdrive to make more connections to your database. Conversely, if your Worker makes few queries that actually need to reach your database or if your database allows a small number of database connections, you can reduce the amount of connections Hyperdrive will make to your database. -All configurations have a minimum of 5 connections, and with a maximum depending on your Workers plan. Refer to the [limits](/hyperdrive/platform/limits/) for details. +All configurations have a minimum of 5 connections, with a maximum depending on your Workers plan. Customers on a Workers Paid plan can set up to 1,500 connections per configuration. ## How Hyperdrive pools database connections Hyperdrive will automatically scale the amount of database connections held open by Hyperdrive depending on your traffic and the amount of load that is put on your database. -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. +The origin connection limit is the maximum number of database connections that Hyperdrive can make to your origin database. This is a soft limit, so set it lower than your origin database connection limit. + +Hyperdrive may create more connections if network disruptions prevent existing connections from being used. ## Restart the connection pool @@ -46,7 +48,7 @@ You can configure connection counts using the Cloudflare dashboard or the Cloudf - **Start conservatively**: Begin with a lower connection count and increase as needed based on your application's performance. - **Monitor database metrics**: Watch your database's connection usage and performance metrics to optimize the connection count. -- **Consider database limits**: Ensure your configured connection count doesn't exceed your database's maximum connection limit. +- **Consider database limits**: Set your configured connection count lower than your database's maximum connection limit. - **Account for multiple configurations**: If you have multiple Hyperdrive configurations connecting to the same database, consider the total connection count across all configurations. ## Next steps diff --git a/src/content/docs/hyperdrive/configuration/tune-connection-pool.mdx b/src/content/docs/hyperdrive/configuration/tune-connection-pool.mdx index 19425cf9338..3491d0310c4 100644 --- a/src/content/docs/hyperdrive/configuration/tune-connection-pool.mdx +++ b/src/content/docs/hyperdrive/configuration/tune-connection-pool.mdx @@ -67,10 +67,12 @@ curl --request PATCH \ -All Hyperdrive configurations have a minimum of 5 connections. The maximum connection count depends on your [Workers plan](/hyperdrive/platform/limits/). +All Hyperdrive configurations have a minimum of 5 connections. Customers on a Workers Paid plan can set up to 1,500 connections per configuration. :::note -The Hyperdrive connection pool limit is a "soft limit". This means that it is possible for Hyperdrive to make more connections to your database than this limit in the event of network failure to ensure high availability. We recommend that you set the Hyperdrive connection limit to be lower than the limit of your origin database to account for occasions where Hyperdrive needs to create more connections for resiliency. +The Hyperdrive origin connection limit is the maximum number of database connections that Hyperdrive can make to your origin database. + +This is a soft limit. Set it lower than your origin database connection limit because Hyperdrive may create more connections if network disruptions prevent existing connections from being used. ::: @@ -82,7 +84,7 @@ You can request adjustments to Hyperdrive's origin connection limits. To request - **Start conservatively**: Begin with a lower connection count and gradually increase it based on your application's performance. - **Monitor database metrics**: Watch your database's connection usage and performance metrics to optimize the connection count. -- **Consider database limits**: Ensure your configured connection count does not exceed your database's maximum connection limit. +- **Consider database limits**: Set your configured connection count lower than your database's maximum connection limit. - **Account for multiple configurations**: If you have multiple Hyperdrive configurations connecting to the same database, consider the total connection count across all configurations. ## Related resources diff --git a/src/content/docs/hyperdrive/platform/limits.mdx b/src/content/docs/hyperdrive/platform/limits.mdx index 9dbd67a1301..30f663bb8cd 100644 --- a/src/content/docs/hyperdrive/platform/limits.mdx +++ b/src/content/docs/hyperdrive/platform/limits.mdx @@ -14,10 +14,10 @@ The following limits apply to Hyperdrive configurations, connections, and querie These limits apply when creating or updating Hyperdrive configurations. -| Limit | Free | Paid | -| ------------------------------ | --------------------- | --------------------- | -| Maximum configured databases | 10 per account | 25 per account | -| Maximum username length [^1] | 63 characters (bytes) | 63 characters (bytes) | +| Limit | Free | Paid | +| --------------------------------- | --------------------- | --------------------- | +| Maximum configured databases | 10 per account | 25 per account | +| Maximum username length [^1] | 63 characters (bytes) | 63 characters (bytes) | | Maximum database name length [^1] | 63 characters (bytes) | 63 characters (bytes) | [^1]: This is a limit enforced by PostgreSQL. Some database providers may enforce smaller limits. @@ -26,23 +26,25 @@ These limits apply when creating or updating Hyperdrive configurations. These limits apply to connections between Hyperdrive and your origin database. -| Limit | Free | Paid | -| ---------------------------------- | ------------------------ | ------------------------- | -| Initial connection timeout | 15 seconds | 15 seconds | -| Idle connection timeout | 10 minutes | 10 minutes | -| Maximum origin database connections (per configuration) [^2] | ~20 connections | ~100 connections | +| Limit | Free | Paid | +| ------------------------------------------------------------ | -------------- | ----------------- | +| Initial connection timeout | 15 seconds | 15 seconds | +| Idle connection timeout | 10 minutes | 10 minutes | +| Maximum origin database connections (per configuration) [^2] | 20 connections | 1,500 connections | -Hyperdrive does not limit the number of concurrent client connections from your Workers. However, Hyperdrive limits connections to your origin database because most hosted databases have connection limits. +The maximum origin database connections value is the maximum number of database connections that Hyperdrive can make to your origin database. Hyperdrive does not limit the number of concurrent client connections from your Workers. -[^2]: Hyperdrive is a distributed system, so a client may be unable to reach an existing pool. In this scenario, a new pool is established with its own connection allocation. This prioritizes availability over strict limit enforcement, which means connection counts may occasionally exceed the listed limits. +Set the Hyperdrive origin connection limit lower than your origin database connection limit. Most hosted databases have connection limits, and Hyperdrive's origin connection limit is a soft limit. + +[^2]: Hyperdrive may create more connections if network disruptions prevent existing connections from being used. This prioritizes availability over strict limit enforcement, which means connection counts may occasionally exceed the listed limits. ### Connection errors When Hyperdrive cannot acquire a connection to your origin database, you may see one of the following errors: -| Error message | Cause | -| ------------- | ----- | -| `Failed to acquire a connection from the pool.` | The connection pool is exhausted because connections are held open too long. Long-running queries or transactions are a common cause. | +| Error message | Cause | +| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Failed to acquire a connection from the pool.` | The connection pool is exhausted because connections are held open too long. Long-running queries or transactions are a common cause. | | `Server connection attempt failed: connection_refused` | Your origin database is rejecting connections. This can occur when a firewall blocks Hyperdrive, or when your database provider's connection limit is exceeded. | For a complete list of error codes, refer to [Troubleshoot and debug](/hyperdrive/observability/troubleshooting/). @@ -51,10 +53,10 @@ For a complete list of error codes, refer to [Troubleshoot and debug](/hyperdriv These limits apply to queries sent through Hyperdrive. -| Limit | Free | Paid | -| ---------------------------------- | --------- | --------- | +| Limit | Free | Paid | +| ---------------------------------- | ---------- | ---------- | | Maximum query (statement) duration | 60 seconds | 60 seconds | -| Maximum cached query response size | 50 MB | 50 MB | +| Maximum cached query response size | 50 MB | 50 MB | Queries exceeding the maximum duration are terminated. Query responses larger than 50 MB are not cached but are still returned to your Worker. diff --git a/src/content/release-notes/hyperdrive.yaml b/src/content/release-notes/hyperdrive.yaml index fecc2da1fea..04ce8ab847f 100644 --- a/src/content/release-notes/hyperdrive.yaml +++ b/src/content/release-notes/hyperdrive.yaml @@ -3,6 +3,16 @@ link: "/hyperdrive/platform/release-notes/" productName: Hyperdrive productLink: "/hyperdrive/" entries: + - publish_date: "2026-09-10" + title: Hyperdrive raises Workers Paid connection limit + description: |- + Customers on a Workers Paid plan can configure up to 1,500 origin database connections per Hyperdrive configuration. + + The origin connection limit is the maximum number of database connections that Hyperdrive can make to your origin database. You can configure this value in the dashboard settings for your Hyperdrive configuration. + + Set this value lower than your origin database's own connection limit to leave room for adjustments. + + Refer to [Hyperdrive limits](/hyperdrive/platform/limits/) for details. - publish_date: "2025-12-04" title: Connect to remote databases during local development with wrangler dev description: |-