Binding reference Bindings

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

Hyperdrive gives Workers a pooled, Cloudflare-managed connection path to existing PostgreSQL databases.

Hyperdrive is modeled in Devflare config, compile flows, local Miniflare wiring, and pure tests through explicit local connection strings.

For local work, point the binding at a local or test PostgreSQL database. Cloudflare still owns the hosted pooling layer, placement, account credentials, and production routing.

Config key
Authoring shape
Best for: Workers that connect to PostgreSQL through Hyperdrive

Add the binding to config

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.

Add when local dev or tests should query a local database without contacting Cloudflare.

Hyperdrive binding authoring

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'postgres-worker',

bindings: {

hyperdrive: {

DB: {

name: 'app-postgres',

localConnectionString: 'postgres://user:pass@localhost:5432/app'

ANALYTICS_DB: { id: 'hyperdrive-id' }

}

})

Use the binding from application code

After Devflare generates the worker env, import from and keep the first Hyperdrive path close to the route, handler, or service method that needs it.

Keep this first path small enough that the config, env binding, and user-visible behavior are easy to review together.

Read one product through Hyperdrive

import postgres from 'postgres'

import { env, getFetchEvent } from 'devflare/runtime'

const sql = postgres(env.DB.connectionString)

export async function fetch(): Promise<Response> {

const event = getFetchEvent()

const slug = new URL(event.request.url).searchParams.get('slug') ?? 'starter-kit'

const [product] = await sql.unsafe(

'select slug, name, price_cents from products where slug = $1 limit 1',

[slug]

)

return product ? Response.json(product) : new Response('not found', { status: 404 })

}

Local and Remote Support

Devflare can run useful Hyperdrive application behavior locally for ordinary development and tests. Cloudflare still owns production limits, quotas, billing, and deployed account behavior.

Full local support when Devflare has a local database connection string for the binding. Start locally with or with ; that lane should cover the normal Hyperdrive application flow without requiring a Cloudflare connection.

Use Cloudflare when the assertion depends on deployed limits, account state, lifecycle behavior, billing, or other production-only Hyperdrive details.

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.

Testing path

Use to override the configured local connection string in CI or per-developer shells.
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.

Local and hosted responsibilities are different

Devflare can wire the local database path. Cloudflare still owns hosted pooling, production credentials, placement, billing, and account state.

Open the next page when you need it

Subpage

Hyperdrive internals

Internals

Check emitted Wrangler , preview behavior, and Cloudflare-specific details.

Subpage

Testing Hyperdrive

Testing

Pick the or with path first, then move to remote checks only when the test needs them.

Subpage

Hyperdrive example

Example

Copy a fuller application path when the quick example is too small.