Cloudflare Workers can connect to and query your data in both SQL and NoSQL databases, including:
- Cloudflare's own D1 serverless SQL database, and Durable Objects with SQLite storage.
- Traditional hosted databases: relational databases such as Postgres and MySQL, using Hyperdrive (recommended) to significantly speed up access, and NoSQL databases such as MongoDB.
- Serverless databases, including Supabase, PlanetScale, and Prisma.
Cloudflare provides two SQL database options native to Workers, both backed by SQLite and accessed through a Workers binding rather than a network connection.
D1 is Cloudflare's own SQL-based, serverless database. It is optimized for global access from Workers, and can scale out with multiple, smaller (10GB) databases, such as per-user, per-tenant or per-entity databases. Similar to some serverless databases, D1 pricing is based on query and storage costs.
Durable Objects offer a lower-level building block: a SQLite-backed Durable Object embeds a private SQLite database (up to 10 GB) that you query synchronously through the SQL storage API (ctx.storage.sql.exec). Because storage is colocated with compute, this suits per-user, per-tenant, or per-entity SQL state and distributed-system coordination. D1 is itself built on Durable Objects.
| Database | Library or Driver | Connection Method |
|---|---|---|
| D1 | Workers binding, integrates with Prisma ↗︎, Drizzle ↗︎, and other ORMs | Workers binding, REST API |
| Durable Objects | SQL storage API (ctx.storage.sql) |
Workers binding |
Traditional databases connect over TCP sockets using a native driver. TCP is the de-facto standard protocol that many databases use for client connectivity, and these drivers are widely compatible with your preferred ORM libraries and query builders.
Relational databases such as PostgreSQL and MySQL connect using their native SQL drivers over TCP.
This also includes serverless databases that are PostgreSQL or MySQL-compatible like Supabase, Neon, or PlanetScale (either MySQL or PostgreSQL), which can be connected to using both native TCP sockets and Hyperdrive or serverless HTTP-based drivers (detailed below).
| Database | Integration | Library or Driver | Connection Method |
|---|---|---|---|
| Postgres | Direct connection | node-postgres ↗︎,Postgres.js ↗︎ | TCP Socket via database driver, using Hyperdrive for optimal performance (optional, recommended) |
| MySQL | Direct connection | mysql2 ↗︎, mysql ↗︎ | TCP Socket via database driver, using Hyperdrive for optimal performance (optional, recommended) |
MongoDB is a document-oriented database that connects over TCP using its native Node.js driver. Hyperdrive does not support MongoDB, so to pool connections and reduce latency, persist the client inside a Durable Object. Refer to Connect to MongoDB for setup instructions.
| Database | Integration | Library or Driver | Connection Method |
|---|---|---|---|
| MongoDB | Direct connection | mongodb ↗︎, mongoose ↗︎ | TCP Socket via native driver |
Serverless databases may provide direct connection to the underlying database, or provide HTTP-based proxies and drivers (also known as serverless drivers).
For PostgreSQL and MySQL serverless databases, you can connect to the underlying database directly using the native database drivers and ORMs you are familiar with, using Hyperdrive (recommended) to speed up connectivity and pool database connections. When you use Hyperdrive, your connection pool is managed across all of Cloudflare regions and optimized for usage from Workers.
You can also use serverless driver libraries to connect to the HTTP-based proxies managed by the database provider. These may also provide connection pooling for traditional SQL databases and reduce the amount of roundtrips needed to establish a secure connection, similarly to Hyperdrive.
| Database | Library or Driver | Connection Method |
|---|---|---|
| PlanetScale ↗︎ | Hyperdrive (MySQL), Hyperdrive (PostgreSQL), @planetscale/database ↗︎ | mysql2, mysql, node-postgres, Postgres.js, or API via client library |
| Supabase ↗︎ | Hyperdrive, @supabase/supabase-js ↗︎ | node-postgres,Postgres.js, or API via client library |
| Prisma ↗︎ | prisma ↗︎ | API via client library |
| Neon ↗︎ | Hyperdrive, @neondatabase/serverless ↗︎ | node-postgres,Postgres.js, or API via client library |
| Hasura ↗︎ | API | GraphQL API via fetch() |
| Upstash Redis ↗︎ | @upstash/redis ↗︎ | API via client library |
| TiDB Cloud ↗︎ | @tidbcloud/serverless ↗︎ | API via client library |
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.
If your database requires authentication, use Wrangler secrets to securely store your credentials. To do this, create a secret in your Cloudflare Workers project using the following wrangler secret command:
wrangler secret put <SECRET_NAME>Then, retrieve the secret value in your code using the following code snippet:
const secretValue = env.<SECRET_NAME>;Use the secret value to authenticate with the external service. For example, if the external service requires an API key or database username and password for authentication, include these in using the relevant service's library or API.
For services that require mTLS authentication, use mTLS certificates to present a client certificate.
- Learn how to connect to an existing PostgreSQL database with Hyperdrive.
- Discover other storage options available for use with Workers.
- Create your first database with Cloudflare D1.