External database integrations: D1, Hyperdrive, or the official driver

Before connecting an external database from Workers, decide whether D1 is enough, then choose between Hyperdrive pooled TCP and the database's official HTTP driver.

INTEGRATIONSINTERMEDIATE20 minutesVerified 2026-08-27

Bottom line first

For structured data with simple query patterns, evaluate D1 first. When you need the full Postgres/MySQL surface or already run an external database, there are two paths — Hyperdrive pooled TCP or the database's official HTTP driver. Hyperdrive does not support SQLite/libSQL, so Turso can only use its official driver.

Four connection paths

Path	Best for	Key limits	Verify before launch
D1 (platform default)	Structured data, single-region reads and writes, simple query patterns	SQLite semantics; cross-database JOINs and stored procedures do not apply	Read/write ratio, migration tooling, capacity ceilings
Hyperdrive + Postgres ecosystem	Existing Postgres (including Neon, Supabase, CockroachDB, Timescale) that benefits from pooling and caching	TLS is mandatory; no LISTEN/NOTIFY, advisory locks, or SQL-level prepared statements	Connection string, role permissions, query latency
Hyperdrive + MySQL ecosystem	Existing MySQL 5.7–8.x or MariaDB (including PlanetScale)	Same mandatory TLS; check the driver against the official support list	Protocol compatibility, slow queries
Official HTTP driver	Workers issuing HTTP/WebSocket requests (Supabase PostgREST, Neon serverless, Turso libSQL, TiDB serverless)	No pooling benefit; every request pays handshake and TLS cost itself	Cold-start latency, vendor rate limits

When D1 is enough

D1 runs in the same region as your Worker, so reads carry almost no network overhead, and the migration toolchain stays inside the platform. If the data model is single-tenant or a handful of related tables, with no dependency on stored procedures or triggers, and the team does not want to operate a second database, start with D1. See choose the right storage service by data shape for the details.

When you need full SQL capability (window functions, CTEs, complex transaction isolation) or data already lives in Supabase/Neon, do not force a migration back to D1 — the detailed trade-offs live on the D1 vs Supabase/Neon comparison page and are not repeated here.

Hyperdrive capabilities and boundaries

Hyperdrive maintains a connection pool from the Cloudflare edge to your origin database and offers query caching, amortizing the TCP/TLS handshake cost of every cold start. Officially supported scope:

Postgres 9.0–17.x, plus protocol-compatible Neon, Supabase, CockroachDB, and Timescale.
MySQL 5.7–8.x and MariaDB, plus protocol-compatible PlanetScale.
TLS is mandatory; the origin must accept encrypted connections.
On Postgres, LISTEN/NOTIFY, advisory locks, and SQL-level prepared statements are not supported (driver-level parameterized queries are unaffected).
SQLite/libSQL is not supported — neither Turso nor local SQLite files can go through Hyperdrive.

wrangler.jsonc

{
  "name": "orders-api",
  "compatibility_date": "2026-08-25",
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<hyperdrive-config-id>", "localConnectionString": "postgres://user:pass@localhost:5432/postgres" }
  ]
}

Choose by three questions

Do you need the full SQL surface? No, and the data model is simple: D1. Yes: next question.
Do you already run an external database? Existing Postgres/MySQL: Hyperdrive first — pooling pays off most for frequent short queries. Starting from zero: compare the free tiers and cold-start behavior of Neon/Supabase/TiDB.
How sensitive are you to cold starts? Very sensitive and on Postgres: Hyperdrive. Able to tolerate a few hundred milliseconds on the first query: the official HTTP driver is simpler, with no extra Hyperdrive configuration to maintain.

Learn the database before configuring the connection

Hyperdrive handles pooling and the edge-to-database path; it does not design schemas, indexes, transactions, backups, or upgrades. For Postgres, continue with the cloud PostgreSQL ownership boundary. For MariaDB, use the MariaDB cloud guide. Then return here to configure connectivity and use the related technology guide network to check the complete responsibility chain.

Verification and troubleshooting

Symptom	Check first	Recovery
Worker reports `connection refused`	Whether the origin allows Cloudflare edge sources and has TLS enabled	Enable TLS, allow the sources, retry
Hyperdrive queries fail with errors	Whether the code uses LISTEN/NOTIFY or advisory locks	Rewrite as polling or a queue-based design
The driver fails to build for Workers	Whether you installed the Node native-socket build	Switch to the package and import path marked Workers-compatible
First query after cold start takes hundreds of milliseconds	Whether you use an HTTP driver against a scale-to-zero origin	Move to Hyperdrive, or accept the latency and add caching

Remote boundary and rollback

Creating a Hyperdrive configuration, writing database-password secrets, and deploying the Worker all change Cloudflare-side state; this page does not run those actions. Rollback runs in reverse order: remove the hyperdrive binding from wrangler.jsonc and redeploy, delete the Hyperdrive configuration in the Cloudflare dashboard, then rotate the database password you wrote — deleting a binding does not revoke a secret, so password rotation is a separate step.

Next: pick the tutorial for your database — Supabase, Neon, Turso, TiDB. General rules for bindings and secrets live in Bindings, environments, and secrets.