You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Fix Hyperdrive overview and get started for MySQL and free tier
* thomasgauvin: update how hyperdrive works for mysql
* thomasgauvin: adapt query caching to mysql
* thomasgauvin: nits & notes for local dev
* update examples for mysql
* typo
* Updating connect to databases guidance in Workers docs
* add supported dbs and redirects
* more redirects fixes
* clarify that support for mysql-compatible databases in work in progress
* fix accidental overwrite
* Quick PCX Review part 1
* Fixing / efficient use of tabs.
* Fixing broken links
* Fixing links, adding missing redirect.
* Fixing redirect
* Update supported versions mysql
---------
Co-authored-by: Jun Lee <[email protected]>
Validate that you can connect to your database from Workers and make queries.
196
+
197
+
<Tabs>
198
+
<TabItemlabel="PostgreSQL">
194
199
195
200
Use Postgres.js to send a test query to validate that the connection has been successful.
196
201
@@ -204,6 +209,24 @@ npx wrangler deploy
204
209
205
210
If you successfully receive the list of `pg_tables` from your database when you access your deployed Worker, your Hyperdrive has now been configured to securely connect to a private database using [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) and [Cloudflare Access](/cloudflare-one/policies/access/).
206
211
212
+
</TabItem>
213
+
<TabItemlabel="MySQL">
214
+
215
+
Use [mysql2](https://github.com/sidorares/node-mysql2) to send a test query to validate that the connection has been successful.
If you successfully receive the list of tables from your database when you access your deployed Worker, your Hyperdrive has now been configured to securely connect to a private database using [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) and [Cloudflare Access](/cloudflare-one/policies/access/).
226
+
227
+
</TabItem>
228
+
</Tabs>
229
+
207
230
## Troubleshooting
208
231
209
232
If you encounter issues when setting up your Hyperdrive configuration with tunnels to a private database, consider these common solutions, in addition to [general troubleshooting steps](/hyperdrive/observability/troubleshooting/) for Hyperdrive:
Copy file name to clipboardExpand all lines: src/content/docs/hyperdrive/configuration/how-hyperdrive-works.mdx
+25-30Lines changed: 25 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,62 +13,57 @@ Traditional databases usually handle a maximum number of connections. With any r
13
13
14
14
Hyperdrive solves these challenges by managing the number of global connections to your origin database, selectively parsing and choosing which query response to cache while reducing loading on your database and accelerating your database queries.
15
15
16
+
## How Hyperdrive makes databases fast globally
17
+
18
+
Hyperdrive accelerates database queries by:
19
+
20
+
- Performing the connection setup for new database connections near your Workers
21
+
- Pooling existing connections near your database
22
+
- Caching query results
23
+
24
+
This ensures you have optimal performance when connecting to your database from Workers (whether your queries are cached or not).
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.
30
+
When a database driver connects to a database from a Cloudflare Worker **directly**, 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.
21
31
22
-
**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.
32
+
**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.
23
33
24
-
## Connection Pooling
34
+
### 2. Connection Pooling
25
35
26
36
Hyperdrive creates a pool of connections to your database that can be reused as your application executes queries against your database.
27
37
28
38
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.
29
39
30
-
When a query hits Hyperdrive, the request is routed to the nearest connection pool.
31
-
32
-
If the connection pool has pre-existing connections, the connection pool will try and reuse that connection.
33
-
40
+
If the connection pool has pre-existing connections, the connection pool will try and reuse that connection (see diagram, label _2. Existing warm connection_).
34
41
If the connection pool does not have pre-existing connections, it will establish a new connection to your database and use that to route your query. This aims at reusing and creating the least number of connections possible as required to operate your application.
35
42
36
43
:::note
37
44
38
45
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.
39
46
:::
40
47
41
-
## Pooling mode
42
-
43
-
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.
44
-
45
-
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.
46
-
47
-
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.
48
-
49
-
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.
48
+
### 3. Query Caching
50
49
51
-
## Unsupported PostgreSQL features:
50
+
Hyperdrive supports caching of non-mutating (read) queries to your database.
52
51
53
-
Hyperdrive does not support the following PostgreSQL features:
52
+
When queries are sent via Hyperdrive, Hyperdrive parses the query and determines whether the query is a mutating (write) or non-mutating (read) query.
54
53
55
-
- SQL-level management of prepared statements, such as using `PREPARE`, `DISCARD`, `DEALLOCATE`, or `EXECUTE`.
- Any modification to per-session state not explicitly documented as supported elsewhere.
54
+
For non-mutating queries, Hyperdrive will cache the response for the configured `max_age`, and whenever subsequent queries are made that match the original, Hyperdrive will return the cached response, bypassing the need to issue the query back to the origin database.
60
55
61
-
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.
56
+
Caching reduces the burden on your origin database and accelerates the response times for your queries.
62
57
63
-
## Query Caching
58
+
## Pooling mode
64
59
65
-
Hyperdrive supports caching of non-mutating (read) queries to your database.
60
+
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.
66
61
67
-
When queries are sent via Hyperdrive, Hyperdrive parses the query and determines whether the query is a mutating (write) or non-mutating (read) query.
62
+
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.
68
63
69
-
For non-mutating queries, Hyperdrive will cache the response for the configured `max_age`, and whenever subsequent queries are made that match the original, Hyperdrive will return the cached response, bypassing the need to issue the query back to the origin database.
64
+
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.
70
65
71
-
Caching reduces the burden on your origin database and accelerates the response times for your queries.
66
+
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.
Copy file name to clipboardExpand all lines: src/content/docs/hyperdrive/configuration/local-development.mdx
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,21 +7,21 @@ sidebar:
7
7
8
8
import { WranglerConfig } from"~/components";
9
9
10
-
Hyperdrive can be used when developing and testing your Workers locally by connecting to any local database instance running on your machine directly. Local development uses [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, to manage local development sessions and state.
10
+
Hyperdrive can be used when developing and testing your Workers locally by connecting to a local database instance running on your machine directly, or a remote database instance. Local development uses [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, to manage local development sessions and state.
11
11
12
-
## Configure local development
13
-
14
-
:::note
12
+
:::note[Note]
15
13
16
-
This guide assumes you are using `wrangler` version `3.27.0` or later.
14
+
You can connect to a local database for local development using the local connection string configurations for Wrangler, as detailed below. This allows you to connect to a local database instance running on your machine directly.
17
15
18
-
If you are new to Hyperdrive and/or Cloudflare Workers, refer to [Hyperdrive tutorial](/hyperdrive/get-started/) to install `wrangler` and deploy their first database.
16
+
You can also connect to a remote database for remote development using the `npx wrangler dev --remote` command, which will use the remote database configured for your Hyperdrive configuration.
19
17
20
18
:::
21
19
20
+
## Configure local development
21
+
22
22
To specify a database to connect to when developing locally, you can:
23
23
24
-
-**Recommended** Create a `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` environmental variable with the connection string of your database. `<BINDING_NAME>` is the name of the binding assigned to your Hyperdrive in your [Wrangler configuration file](/workers/wrangler/configuration/) or Pages configuration. This allows you to avoid committing potentially sensitive credentials to source control in your Wrangler configuration file, if your test/development database is not ephemeral. If you have configured multiple Hyperdrive bindings, replace `<BINDING_NAME>` with the unique binding name for each.
24
+
-**Recommended:** Create a `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` environmental variable with the connection string of your database. `<BINDING_NAME>` is the name of the binding assigned to your Hyperdrive in your [Wrangler configuration file](/workers/wrangler/configuration/) or Pages configuration. This allows you to avoid committing potentially sensitive credentials to source control in your Wrangler configuration file, if your test/development database is not ephemeral. If you have configured multiple Hyperdrive bindings, replace `<BINDING_NAME>` with the unique binding name for each.
25
25
- Set `localConnectionString` in the Wrangler configuration file.
26
26
27
27
If both the `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` environmental variable and `localConnectionString` in the Wrangler configuration file are set, `wrangler dev` will use the environmental variable instead. Use `unset WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` to unset any existing environmental variables.
0 commit comments