How Devflare wires Hyperdrive from config to runtime
Hyperdrive gives Workers a pooled, Cloudflare-managed connection path to existing PostgreSQL databases.
Hyperdrive uses the same normalize-and-resolve pattern as KV and D1, and local runtime config is driven by the binding connection string.
That fallback behavior is worth documenting explicitly because it changes how you should think about preview isolation and cleanup for database-backed flows.
- Normalization
- Hyperdrive follows the same name-versus-id normalization family as KV and D1
- Compile target
- Wrangler
- Preview note
- Preview Hyperdrive configs may fall back to the base config when a preview clone cannot be materialized
How authored config becomes Wrangler config
Hyperdrive authoring accepts a string, , or , and Devflare normalizes those into one internal binding shape so later code can treat them consistently.
That part looks familiar if you already understand KV or D1. The unusual part is preview lifecycle, not the authored schema.
Hyperdrive config and emitted Wrangler output
Use this when you need to check how the Devflare config becomes Wrangler-compatible config.
What local runtime support covers
- Devflare passes into Miniflare so local Worker code can use the normal Hyperdrive binding shape.
- and the legacy override config for local runs.
- Pure tests can use or when the application code only needs the connection string.
Compile, preview, and cleanup behavior
- Build and deploy resolve name-based Hyperdrive bindings to real configuration ids before generating output.
- Preview resource logic cannot always clone a base Hyperdrive config because Cloudflare does not expose stored credentials for that workflow.
- When a preview Hyperdrive config is missing but the base config exists, Devflare can fall back to the base binding and warn instead of pretending isolation happened.
This is a lifecycle caveat, not a syntax caveat
The config shape is straightforward. The reason Hyperdrive needs extra documentation is the preview and credential story, not the authoring syntax.
Cloudflare docs vs the Devflare layer
Cloudflare Hyperdrive docs is the platform reference. Use this internals page when you need to compare Cloudflare's product docs with Devflare config, generated env types, local support, and preview behavior for .
| Question | Cloudflare docs | This Devflare page |
|---|---|---|
| Primary focus | Platform reference for database acceleration, connection strings, limits, and supported databases. | How to author , what the runtime surface looks like, and how Hyperdrive fits a Devflare project. |
| Testing and runtime lens | Cloudflare’s docs focus on the raw binding API, product semantics, and platform limits for the binding itself. | Full local support when Devflare has a local database connection string for the binding. Use the Devflare guidance when you need the honest local harness or the right remote gate instead of only the product API shape. |
| When to open it | When you need the platform contract, limits, APIs, or account-level product details. | When you are wiring, testing, previewing, or reviewing the binding inside a Devflare app. |
Previous
Hyperdrive
Hyperdrive is modeled in Devflare config, compile flows, local Miniflare wiring, and pure tests through explicit local connection strings.
Next
Testing Hyperdrive
Hyperdrive testing should start with a local connection string, then add a focused query test against the database shape your app actually uses.