Binding reference Bindings

Use Hyperdrive when the worker needs a real PostgreSQL path behind Cloudflare’s pooling layer

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.

That is not a reason to avoid it — it is a reason to document it honestly. The binding is supported, yet the strongest evidence in the repo focuses on presence, connection info, and targeted integration rather than a giant local mock universe.

Config key: bindings.hyperdrive
Authoring shape: Record<string, string | { name: string } | { id: string }>
Best for: Workers that connect to PostgreSQL through Hyperdrive

Author it in the simplest shape that still says what you mean

Hyperdrive follows the same stable-name instinct as KV and D1: author a readable name in source when you can, then let Devflare resolve ids later when a flow actually needs them.

The main difference is operational. Hyperdrive has credential and infrastructure constraints that make preview lifecycle trickier than storage bindings like KV or R2.

Hyperdrive binding authoring

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'postgres-worker',

bindings: {

hyperdrive: {

DB: 'app-postgres',

LEGACY_DB: { id: 'hyperdrive-id' }

}

})

When this binding fits best

Use Hyperdrive when the worker needs PostgreSQL and you want the Cloudflare-managed connection path rather than raw direct wiring.
It fits best when a real Postgres database already exists and the worker boundary should speak to it deliberately.
If your data is already a comfortable fit for D1, D1 may still be the simpler first choice.

Notes worth keeping visible

The repo evidence for local Hyperdrive ergonomics is thinner than the local stories for D1, KV, or R2.
Preview-scoped Hyperdrive configs are not auto-cloned from the base configuration because stored credentials are not always available for that.
When a preview Hyperdrive config does not exist, Devflare may fall back to the base configuration and warn.

Supported does not mean equally local-friendly

Hyperdrive belongs in the binding library, but its test guidance should stay more conservative than the guidance for D1 or KV.

Cloudflare docs vs the Devflare layer

Cloudflare Hyperdrive docs is the platform reference. This page is the Devflare translation layer: keep readable in source, understand the typed env surface, and know which local, preview, or remote lane actually matches the binding.

Reference

Cloudflare Hyperdrive docs

Cloudflare Docs

Platform reference for database acceleration, connection strings, limits, and supported databases.

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.	Supported, but with a narrower proven local test story. 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.

Go deeper only if this one-page guide stops being enough

Subpage

Hyperdrive internals

Internals

See normalization, Wrangler , and the preview or runtime details behind the authored shape.

Subpage

Testing Hyperdrive

Testing

Start from plus small binding or smoke checks and only escalate when the binding or deployment model genuinely needs it.

Subpage

Hyperdrive example

Example

Adapt one small end-to-end path before you hide the binding behind a bigger abstraction.