Under the hood Bindings

How Devflare wires Hyperdrive from config to runtime

Hyperdrive uses the same normalize-and-resolve pattern as KV and D1, but preview lifecycle includes a fallback path instead of guaranteed preview cloning.

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

Devflare normalizes the authored shape before it does anything louder

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 from authored config to generated output

Keep the binding readable in source, then inspect only the Wrangler-facing slice Devflare emits when the config is compiled.

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'postgres-worker',

bindings: {

hyperdrive: {

DB: 'app-postgres',

LEGACY_DB: { id: 'hyperdrive-id' }

}

})

Local runtime support depends on what Devflare can model directly

The repo shows Hyperdrive bindings exposing connection-oriented information such as , and some smoke paths also allow a -style helper.
I did not find the same rich bridge-level local helper story that exists for D1, KV, or R2, which is why the docs should stay cautious here.
The strongest proven local habit is to assert the binding exists and to use targeted integration for database behavior that really matters.

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.

Hyperdrive

Hyperdrive is modeled in Devflare config and compile flows like other name-based resources, but its tested local ergonomics are thinner than D1 or KV.

Testing Hyperdrive

Hyperdrive testing should start smaller and more cautiously than D1 testing: prove the binding exists, then add targeted integration where the real database path matters.