Skip to content

Commit e25f929

Browse files
elithrarelithrar
committed
Improve Hyperdrive limits documentation clarity
Reorganize limits into logical sections (configuration, connection, query) with clearer descriptions of when each limit applies. Add connection error messages with their causes and link to troubleshooting for full error list.
1 parent c00265d commit e25f929

File tree

1 file changed

+48
-19
lines changed

1 file changed

+48
-19
lines changed

‎src/content/docs/hyperdrive/platform/limits.mdx‎

Lines changed: 48 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,58 @@ sidebar:
55
order: 2
66
---
77

8-
The following limits apply to Hyperdrive configuration, connections, and queries made to your configured origin databases.
8+
The following limits apply to Hyperdrive configurations, connections, and queries made to your configured origin databases.
99

10-
| Feature | Free | Paid |
11-
| -------------------------------------------------- | ------------------------ | ------------------------- |
12-
| Maximum configured databases | 10 per account | 25 per account |
13-
| Initial connection timeout | 15 seconds | 15 seconds |
14-
| Idle connection timeout | 10 minutes | 10 minutes |
15-
| Maximum cached query response size | 50 MB | 50 MB |
16-
| Maximum query (statement) duration | 60 seconds | 60 seconds |
17-
| Maximum username length [^1] | 63 characters (bytes) | 63 characters (bytes) |
18-
| Maximum database name length [^1] | 63 characters (bytes) | 63 characters (bytes) |
19-
| Maximum potential origin database connections (per configuration) [^2] | approx. \~20 connections | approx. \~100 connections |
10+
## Configuration limits
2011

21-
:::note
22-
Hyperdrive does not have a hard limit on the number of concurrent _client_ connections made from your Workers.
12+
These limits apply when creating or updating Hyperdrive configurations.
2313

24-
As many hosted databases have limits on the number of unique connections they can manage, Hyperdrive attempts to keep number of concurrent pooled connections to your origin database lower.
25-
:::
14+
| Limit | Free | Paid |
15+
| ------------------------------ | --------------------- | --------------------- |
16+
| Maximum configured databases | 10 per account | 25 per account |
17+
| Maximum username length [^1] | 63 characters (bytes) | 63 characters (bytes) |
18+
| Maximum database name length [^1] | 63 characters (bytes) | 63 characters (bytes) |
2619

2720
[^1]: This is a limit enforced by PostgreSQL. Some database providers may enforce smaller limits.
2821

29-
[^2]: Hyperdrive is a distributed system, so it is possible for a client to be unable to reach an existing pool. In this scenario, a new pool will be established, with its own allocation of connections. This favors availability over strictly enforcing limits, but does mean that it is possible in edge cases to overshoot the normal connection limit.
22+
## Connection limits
3023

31-
:::note
32-
You can request adjustments to limits that conflict with your project goals by contacting Cloudflare. Not all limits can be increased. To request an increase, submit a [Limit Increase Request](https://forms.gle/ukpeZVLWLnKeixDu7) and we will contact you with next steps. We also regularly monitor the Hyperdrive channel in [Cloudflare's Discord community](https://discord.cloudflare.com/) and can answer questions regarding limits and requests.
33-
:::
24+
These limits apply to connections between Hyperdrive and your origin database.
25+
26+
| Limit | Free | Paid |
27+
| ---------------------------------- | ------------------------ | ------------------------- |
28+
| Initial connection timeout | 15 seconds | 15 seconds |
29+
| Idle connection timeout | 10 minutes | 10 minutes |
30+
| Maximum origin database connections (per configuration) [^2] | ~20 connections | ~100 connections |
31+
32+
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.
33+
34+
[^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.
35+
36+
### Connection errors
37+
38+
When Hyperdrive cannot acquire a connection to your origin database, you may see one of the following errors:
39+
40+
| Error message | Cause |
41+
| ------------- | ----- |
42+
| `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. |
43+
| `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. |
44+
45+
For a complete list of error codes, refer to [Troubleshoot and debug](/hyperdrive/observability/troubleshooting/).
46+
47+
## Query limits
48+
49+
These limits apply to queries sent through Hyperdrive.
50+
51+
| Limit | Free | Paid |
52+
| ---------------------------------- | --------- | --------- |
53+
| Maximum query (statement) duration | 60 seconds | 60 seconds |
54+
| Maximum cached query response size | 50 MB | 50 MB |
55+
56+
Queries exceeding the maximum duration are terminated. Query responses larger than 50 MB are not cached but are still returned to your Worker.
57+
58+
## Request a limit increase
59+
60+
You can request adjustments to limits that conflict with your project goals by contacting Cloudflare. Not all limits can be increased.
61+
62+
To request an increase, submit a [Limit Increase Request form](https://forms.gle/ukpeZVLWLnKeixDu7). You can also ask questions in the Hyperdrive channel on [Cloudflare's Discord community](https://discord.cloudflare.com/).

0 commit comments

Comments
 (0)