ADR-0004: Hyperdrive, not the Neon serverless driver

Status: Accepted
Date: 2026-07-30
Supersedes: —
Superseded by: —

Context

Following ADR-0003, Workers need to reach Postgres. Workers are short-lived and highly concurrent, so raw connections don’t work — something must pool.

There are three candidate mechanisms and they are mutually redundant: Cloudflare Hyperdrive, the @neondatabase/serverless driver, and Neon’s own connection pooler.

Decision

Use Cloudflare Hyperdrive with a standard Postgres driver — node-postgres (pg) or postgres.js.

Explicitly:

Do not use @neondatabase/serverless.
Do not enable Neon’s own connection pooler underneath.
Access the connection string via the HYPERDRIVE binding, never a raw DATABASE_URL.

Rationale

Hyperdrive is included in all Workers plans including free. It pools connections across Cloudflare’s network and caches popular queries. The Neon serverless driver solves the same problem a second time, and Neon themselves advise against stacking their pooler beneath another one.

This is the single most likely thing for an agent to get wrong, because @neondatabase/serverless is overwhelmingly the pattern in training data for “Neon on Workers”. It is wrong for this project specifically.

Consequences

Requires nodejs_compat in compatibility_flags or the driver fails at runtime.
Requires compatibility_date ≥ 2025-04-01, otherwise process.env is empty at runtime and config parsing fails in a way the error message does not explain.
Recorded as a trap in AGENTS.md, because default behaviour contradicts it.