Binding strategy Guides

Choose the right storage binding first, then let the binding guides own the mechanics

Use this page to choose between KV, D1, R2, and Hyperdrive. Once the shape is clear, open the binding-specific guide for authoring, testing, and examples instead of reading several smaller pages that all repeat the same decision badly.

This is the storage chooser, not a second binding reference shelf. Use it when the question is “which storage shape fits this worker?” Then jump into the guide that owns the actual runtime, compile, testing, and preview details for that storage binding.

Best for: Choosing between KV, D1, R2, and Hyperdrive before you dive into one binding guide
Main question: Is the data keyed, query-shaped, object-shaped, or an existing remote database connection?
Safest default: Prefer stable names in config when the binding supports them
Open next: The specific binding guide once the storage shape is clear

Choose the storage shape before you choose the syntax

The weirdest storage mistakes usually come from choosing by familiarity instead of by data shape. Devflare already has strong per-binding guides for authoring and testing, so this page should stay at the decision boundary instead of pretending to be four shorter reference pages glued together.

Once the storage shape is obvious, the binding guide should take over. That keeps the library cleaner and makes the per-binding pages easier to trust.

Binding	Reach for it when	Usually the wrong fit
	You need keyed lookups, cache-like state, feature flags, or lightweight session markers.	You need relational queries, joins, or object delivery.
	You need SQL, relations, filters, or schema-shaped data.	You only need key lookup or one blob of file data.
	You need objects, uploads, generated files, or browser-facing file delivery through a Worker.	You need query semantics or tiny cache records.
	You already have a remote PostgreSQL system and the worker should reach it through Cloudflare acceleration.	A local-first or greenfield schema could live in D1 instead.

The page boundary is deliberate

This page should help you pick the binding. The actual binding guides should explain how to author it, test it, preview it, and ship it.

Stable names are still the calmest authoring default

Name-based storage bindings stay readable in source review and let Devflare resolve the noisy ids later when build, deploy, or config-print flows actually need them.

That rule does not mean every binding works the same way, but it does keep the source-of-truth shape calmer for KV, D1, and Hyperdrive while R2 keeps its already-readable bucket names.

Stable-name storage authoring

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'storage-worker',

bindings: {

kv: {

CACHE: { name: 'cache-kv' }

d1: {

DB: { name: 'app-db' },

AUDIT: { id: 'existing-d1-id' }

hyperdrive: {

POSTGRES: 'app-postgres'

r2: {

ASSETS: 'app-assets'

}

})

R2 still needs an explicit browser-delivery boundary

Devflare gives you real R2 bindings in worker code and tests, but it does not promise a stable browser-facing local bucket URL contract. If the browser needs the file in local dev, route through the app instead of assuming the bucket origin is the interface.

Public assets

Use a public bucket on a custom domain when anonymous reads are the product, not an accident.

Private assets

Keep the bucket private and serve through a Worker that owns auth, headers, and cache policy.

Direct uploads

Mint short-lived upload URLs from the backend and store object keys instead of pretending permanent raw URLs are the whole product.

Guide

R2 uploads & delivery

R2 architecture

Open this when the real question is presigned uploads, public versus private delivery, Access protection, signed custom-domain media links, or the right dev-versus-production posture.

Worker-gated file serving keeps the app boundary visible

import type { FetchEvent } from 'devflare/runtime'

export async function GET({ env, params }: FetchEvent<DevflareEnv>): Promise<Response> {

const object = await env.FILES.get(params.key)

if (!object) {

return new Response('Not Found', { status: 404 })

}

return new Response(object.body, {

headers: {

'Content-Type': object.httpMetadata?.contentType ?? 'application/octet-stream',

'Cache-Control': 'private, max-age=0'

}

})

}

Open the binding guide that owns the mechanics

Binding guide

KV

Open the KV guide when the storage shape is keyed lookup, cache-like state, or namespace lifecycle.

Binding guide

D1

Open the D1 guide when the storage shape is query-driven and you need the actual SQL-shaped runtime contract.

Binding guide

R2

Open the R2 guide when the real question is bucket usage, testing, preview naming, or file delivery details.

Binding guide

Hyperdrive

Open the Hyperdrive guide when the worker is reaching an existing PostgreSQL system and the operational caveats matter more than the storage taxonomy.

Feature index

This page is the compact feature support index that keeps support level, Cloudflare boundary, test helper, preview lifecycle, and docs links in one place.

R2 uploads & delivery

Use presigned URLs for direct uploads, public buckets on custom domains for truly public assets, and private buckets plus Worker auth for protected files. Keep out of production, and when a preview or environment needs its own bucket, scope it intentionally instead of borrowing production storage.