Connect a Cloudflare Worker to an existing Postgres or MySQL database through Hyperdrive with connection pooling and query caching

Documented steps

1. Prerequisites: a Cloudflare account, Node.js 16.17.0+, and a PostgreSQL or MySQL database that is publicly reachable or exposed via Cloudflare Tunnel.
2. Run `npx wrangler login`, then scaffold a Worker: `npm create cloudflare@latest -- hyperdrive-tutorial` (Hello World example > Worker only > TypeScript).
3. Add the compatibility flag the Postgres/MySQL drivers require in wrangler.jsonc: `"compatibility_flags": ["nodejs_compat"]` alongside a `compatibility_date`.
4. Create the Hyperdrive config: `npx wrangler hyperdrive create <CONFIG_NAME> --connection-string="<POSTGRES_CONNECTION_URI>"`, where the URI is the standard `postgres` scheme form your database provider issues (host, port, database, and credentials). Use the `mysql` scheme instead for MySQL. Never commit that URI — Wrangler stores it server-side and returns only a config id.
5. Optionally set caching behavior at creation with `--caching-disabled` or `--max-age=<seconds>`; the default max_age is 60 seconds.
6. Bind the returned config id in wrangler.jsonc: `"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<YOUR_CONFIG_ID>" }]`.
7. Install a driver: `npm i pg` plus `npm i -D @types/pg` for node-postgres, or `npm i mysql2` for MySQL. Postgres.js is also supported.
8. Build the client from the binding's connection string: `const sql = new Client({ connectionString: env.HYPERDRIVE.connectionString }); await sql.connect(); await sql.query(...)`.
9. Deploy with `npx wrangler deploy`. Hyperdrive then pools and reuses origin connections globally, removing per-request TCP/TLS setup cost.
10. Leave caching on for read-heavy workloads. Only parameterized read-only SELECTs without volatile functions (NOW(), RANDOM(), LASTVAL()) are cached; INSERT/UPDATE/CREATE and similar mutating statements never are.
11. Tune caching later with `npx wrangler hyperdrive update <CONFIG_ID> --caching-disabled` or a new `--max-age` (ceiling 1 hour). A built-in 15-second stale_while_revalidate window serves stale results while refreshing.
12. For reads that must never be stale (post-write reads, auth and permission checks), create a SECOND Hyperdrive config with `--caching-disabled` and bind it separately, then route those queries through it.
13. To reach a database that is not publicly exposed, set up Cloudflare Tunnel plus Cloudflare Access: install `cloudflared`, route a public hostname to the DB port, then `wrangler hyperdrive create` with the discrete flags instead of a URI: `--host=<TUNNEL_HOSTNAME>`, `--database=<DATABASE>`, the database user and credential flags, and the two Cloudflare Access service-token flags. OMIT `--port` — tunnel hostname routing determines the destination.
14. Check limits before scaling: 10 configs per account on Free / 25 on Paid, roughly 20 origin connections per config on Free / 100 on Paid, 15 s connection timeout, 10-minute idle timeout, 60 s max query duration, 50 MB max cached response size.
15. Official documentation (verify before relying on limits, which change): https://developers.cloudflare.com/hyperdrive/ | https://developers.cloudflare.com/hyperdrive/get-started/ | https://developers.cloudflare.com/hyperdrive/configuration/query-caching/ | https://developers.cloudflare.com/hyperdrive/platform/limits/ | https://developers.cloudflare.com/hyperdrive/configuration/connect-to-private-database/