Skip to content

Commit b57e70e

Browse files
thomasgauvinthomasgauvin
committed
Updating connect to databases guidance in Workers docs
1 parent 7ba77c0 commit b57e70e

File tree

5 files changed

+188
-42
lines changed

5 files changed

+188
-42
lines changed

‎src/content/docs/hyperdrive/examples/connect-to-mysql/index.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,6 @@ Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/#
6060
| mysql | [mysql documentation](https://github.com/mysqljs/mysql) | `[email protected]` | Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date = "2024-09-23"` - refer to [Node.js compatibility](/workers/runtime-apis/nodejs). Requires wrangler `3.78.7` or later. |
6161
| Drizzle | [Drizzle documentation](https://orm.drizzle.team/) | Requires `[email protected]` | |
6262
| Kysely | [Kysely documentation](https://kysely.dev/) | Requires `[email protected]` | |
63-
| Prisma | [Prisma documentation](https://www.prisma.io/) | Requires `[email protected]` | |
64-
| TypeORM | [Kysely documentation](https://typeorm.io/) | Requires `[email protected]` | |
6563

6664
^ _The marked libraries can use either mysql or mysql2 as a dependency._
6765

@@ -159,6 +157,13 @@ export default {
159157
} satisfies ExportedHandler<Env>;
160158
```
161159

160+
## Identify connections from Hyperdrive
161+
162+
To identify active connections to your MySQL database server from Hyperdrive:
163+
164+
- Hyperdrive's connections to your database will show up with `Cloudflare Hyperdrive` in the `PROGRAM_NAME` column in the `performance_schema.threads` table.
165+
- Run `SELECT DISTINCT USER, HOST, PROGRAM_NAME FROM performance_schema.threads WHERE PROGRAM_NAME = 'Cloudflare Hyperdrive'` to show whether Hyperdrive is currently holding a connection (or connections) open to your database.
166+
162167
## Next steps
163168

164169
- Refer to the list of [supported database integrations](/workers/databases/connecting-to-databases/) to understand other ways to connect to existing databases.

‎src/content/docs/workers/databases/connecting-to-databases.mdx‎

Lines changed: 54 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -9,39 +9,68 @@ description: Learn about the different kinds of database integrations Cloudflare
99

1010
Cloudflare Workers can connect to and query your data in both SQL and NoSQL databases, including:
1111

12-
- Traditional hosted relational databases, including Postgres and MySQL.
13-
- Serverless databases: Supabase, MongoDB Atlas, PlanetScale, FaunaDB, and Prisma.
1412
- Cloudflare's own [D1](/d1/), a serverless SQL-based database.
13+
- Traditional hosted relational databases, including Postgres and MySQL, using [Hyperdrive](/hyperdrive/) (recommended) to significantly speed up access.
14+
- Serverless databases, including Supabase, MongoDB Atlas, PlanetScale, FaunaDB, and Prisma.
1515

16-
| Database | Integration | Library or Driver | Connection Method |
17-
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
18-
| [Postgres](/workers/tutorials/postgres/) | - | [Postgres.js](https://github.com/porsager/postgres),[node-postgres](https://node-postgres.com/) | [Hyperdrive](/hyperdrive/) |
19-
| [Postgres](/workers/tutorials/postgres/) | - | [deno-postgres](https://github.com/cloudflare/worker-template-postgres) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver |
20-
| [MySQL](/workers/tutorials/postgres/) | - | [deno-mysql](https://github.com/cloudflare/worker-template-mysql) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver |
21-
| [Fauna](https://docs.fauna.com/fauna/current/build/integration/cloudflare/) | [Yes](/workers/databases/native-integrations/fauna/) | [fauna](https://github.com/fauna/fauna-js) | API through client library |
22-
| [PlanetScale](https://planetscale.com/blog/introducing-the-planetscale-serverless-driver-for-javascript) | [Yes](/workers/databases/native-integrations/planetscale/) | [@planetscale/database](https://github.com/planetscale/database-js) | API via client library |
23-
| [Supabase](https://github.com/supabase/supabase/tree/master/examples/with-cloudflare-workers) | [Yes](/workers/databases/native-integrations/supabase/) | [@supabase/supabase-js](https://github.com/supabase/supabase-js) | API via client library |
24-
| [Prisma](https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-cloudflare-workers) | No | [prisma](https://github.com/prisma/prisma) | API via client library |
25-
| [Neon](https://blog.cloudflare.com/neon-postgres-database-from-workers/) | [Yes](/workers/databases/native-integrations/neon/) | [@neondatabase/serverless](https://neon.tech/blog/serverless-driver-for-postgres/) | API via client library |
26-
| [Hasura](https://hasura.io/blog/building-applications-with-cloudflare-workers-and-hasura-graphql-engine/) | No | API | GraphQL API via fetch() |
27-
| [Upstash Redis](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/) | [Yes](/workers/databases/native-integrations/upstash/) | [@upstash/redis](https://github.com/upstash/upstash-redis) | API via client library |
28-
| [TiDB Cloud](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-cloudflare) | No | [@tidbcloud/serverless](https://github.com/tidbcloud/serverless-js) | API via client library |
29-
30-
:::note
16+
### D1 SQL database
17+
18+
D1 is Cloudflare's own SQL-based, serverless database. It is optimized for global access from Workers, and can
19+
scale out with multiple, smaller (10GB) databases, such as per-user, per-tenant or per-entity databases. Similar to some serverless databases,
20+
D1 pricing is based on query and storage costs.
21+
22+
| Database | Library or Driver | Connection Method |
23+
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
24+
| [D1](/d1/) | [Workers binding](/d1/worker-api/), integrates with [Prisma](https://www.prisma.io/), [Drizzle](https://orm.drizzle.team/), and other ORMs | [Workers binding](/d1/worker-api/), [REST API](/api/resources/d1/subresources/database/methods/create/) |
25+
26+
### Traditional SQL databases
27+
28+
Traditional databases use SQL drivers that use [TCP sockets](/workers/runtime-apis/tcp-sockets/) to connect to the database. TCP is the de-facto standard protocol that many databases, such as PostgreSQL and MySQL, use for client connectivity.
29+
These drivers are also widely compatible with your preferred ORM libraries and query builders.
30+
31+
This also includes serverless databases that are PostgreSQL or MySQL-compatible like [Supabase](/hyperdrive/examples/connect-to-postgres/neon/), [Neon](/hyperdrive/examples/connect-to-postgres/neon/) or [PlanetScale](/hyperdrive/examples/connect-to-mysql/planetscale/),
32+
which can be connected to using both native [TCP sockets and Hyperdrive](/hyperdrive/) or [serverless HTTP-based drivers](/workers/databases/connecting-to-databases/#serverless-databases) (detailed below).
33+
34+
| Database | Integration | Library or Driver | Connection Method |
35+
| ---------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
36+
| [Postgres](/workers/tutorials/postgres/) | Direct connection | [Postgres.js](https://github.com/porsager/postgres),[node-postgres](https://node-postgres.com/) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver, using [Hyperdrive](/hyperdrive/) for optimal performance (optional, recommended) |
37+
| [MySQL](/workers/tutorials/mysql/) | Direct connection | [mysql2](https://github.com/sidorares/node-mysql2), [mysql](https://github.com/mysqljs/mysql) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver, using [Hyperdrive](/hyperdrive/) for optimal performance (optional, recommended) |
38+
39+
:::note[Speed up database connectivity with Hyperdrive]
40+
41+
Connecting to SQL databases with TCP sockets requires multiple roundtrips to establish a secure connection before a query to the database is made.
42+
Since a connection must be re-established on every Worker invocation, this adds unnecessary latency.
43+
44+
[Hyperdrive](/hyperdrive/) solves this by pooling database connections globally to eliminate unnecessary roundtrips and speed up your database access. Learn more about [how Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).
3145

32-
If you do not see an integration listed or have an integration to add, complete and submit the [Cloudflare Developer Platform Integration form](https://forms.gle/iaUqLWE8aezSEhgd6).
3346
:::
3447

35-
Once you have installed the necessary packages, use the APIs provided by these packages to connect to your database and perform operations on it. Refer to detailed links for service-specific instructions.
48+
### Serverless databases
49+
50+
Serverless databases provide HTTP-based proxies and drivers, also known as serverless drivers. These address the lack of connection reuse between Worker invocation similarly to [Hyperdrive](/hyperdrive/) for traditional SQL databases.
51+
By providing a way to query your database with HTTP, these serverless databases and drivers eliminate several roundtrips needed to establish a secure connection.
3652

37-
## Connect to a database from a Worker
53+
| Database | Integration | Library or Driver | Connection Method |
54+
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------- |
55+
| [Fauna](https://docs.fauna.com/fauna/current/build/integration/cloudflare/) | [Yes](/workers/databases/native-integrations/fauna/) | [fauna](https://github.com/fauna/fauna-js) | API through client library |
56+
| [PlanetScale](https://planetscale.com/blog/introducing-the-planetscale-serverless-driver-for-javascript) | [Yes](/workers/databases/native-integrations/planetscale/) | [@planetscale/database](https://github.com/planetscale/database-js) | API via client library |
57+
| [Supabase](https://github.com/supabase/supabase/tree/master/examples/with-cloudflare-workers) | [Yes](/workers/databases/native-integrations/supabase/) | [@supabase/supabase-js](https://github.com/supabase/supabase-js) | API via client library |
58+
| [Prisma](https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-cloudflare-workers) | No | [prisma](https://github.com/prisma/prisma) | API via client library |
59+
| [Neon](https://blog.cloudflare.com/neon-postgres-database-from-workers/) | [Yes](/workers/databases/native-integrations/neon/) | [@neondatabase/serverless](https://neon.tech/blog/serverless-driver-for-postgres/) | API via client library |
60+
| [Hasura](https://hasura.io/blog/building-applications-with-cloudflare-workers-and-hasura-graphql-engine/) | No | API | GraphQL API via fetch() |
61+
| [Upstash Redis](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/) | [Yes](/workers/databases/native-integrations/upstash/) | [@upstash/redis](https://github.com/upstash/upstash-redis) | API via client library |
62+
| [TiDB Cloud](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-cloudflare) | No | [@tidbcloud/serverless](https://github.com/tidbcloud/serverless-js) | API via client library |
3863

39-
There are four ways to connect to a database from a Worker:
64+
:::note[Easier setup with database integrations]
4065

41-
1. With [Hyperdrive](/hyperdrive/) (recommended), which dramatically speeds up accessing traditional databases. Hyperdrive currently supports PostgreSQL and PostgreSQL-compatible database providers.
42-
2. [Database Integrations](/workers/databases/native-integrations/): Simplifies authentication by managing credentials on your behalf and includes support for PlanetScale, Neon and Supabase.
43-
3. [TCP Socket API](/workers/runtime-apis/tcp-sockets): A direct TCP connection to a database. TCP is the de-facto standard protocol that many databases, such as PostgreSQL and MySQL, use for client connectivity.
44-
4. HTTP- or WebSocket-based serverless drivers: Many hosted databases support a HTTP or WebSocket API to enable either clients to connect from environments that do not support TCP, or as their preferred connection protocol.
66+
[Database Integrations](/workers/databases/native-integrations/) simplify the authentication for serverless database drivers
67+
by managing credentials on your behalf and includes support for PlanetScale, Neon and Supabase.
68+
69+
If you do not see an integration listed or have an integration to add, complete and submit the [Cloudflare Developer Platform Integration form](https://forms.gle/iaUqLWE8aezSEhgd6).
70+
71+
:::
72+
73+
Once you have installed the necessary packages, use the APIs provided by these packages to connect to your database and perform operations on it. Refer to detailed links for service-specific instructions.
4574

4675
## Authentication
4776

0 commit comments

Comments
 (0)