Testing Bindings

Test D1 the way Devflare expects it to run

D1 is Cloudflare’s serverless SQL database for applications that run on Workers.

D1 is one of the easiest bindings to test meaningfully with Devflare because the local runtime already speaks the same database API your worker uses.

Start with , then either query the database directly through or exercise it through your real routes. Both are normal, not exotic.

Best for: Query behavior, route-level database flows, and schema-aware worker tests
Default harness: with or
Escalate when: You need migration, provisioning, or branch-scoped preview verification

Start with the default test loop

The cleanest D1 test loop mirrors how the worker really behaves: boot the test context, run a small query, and assert the returned row or route result.

If a helper wraps the query logic, keep one direct database test around anyway so the underlying binding contract stays visible.

A tiny D1 test through the local harness

import { afterAll, beforeAll, expect, test } from 'bun:test'

import { createTestContext, env } from 'devflare/test'

beforeAll(() => createTestContext())

afterAll(() => env.dispose())

test('D1 answers a simple health query', async () => {

const row = await env.DB.prepare('select 1 as ok').first<{ ok: number }>()

expect(row?.ok).toBe(1)

})

The helper surface to remember

Use when the binding itself is the thing you care about.
Use when the database matters because a route, queue consumer, or other handler reaches it.
Keep the schema setup close to the test when possible so the query story stays visible.

When to move beyond the default harness

Local tests are excellent for query logic, but they are not a substitute for migration review or account-side database provisioning checks.
If the assertion is really about a business route, do not collapse the entire behavior down to one raw SQL assertion and pretend that is the full story.
Preview-specific D1 isolation is worth its own higher-level check when branch data boundaries matter.

Do not let SQL disappear into helper fog

One reason D1 feels good in Devflare is that the runtime API is still recognizable. Keep at least one test close enough to see the actual query behavior.

D1 internals

D1 uses the same normalize-then-resolve pattern as KV, but compiles to Wrangler and exposes a relational local runtime surface.

D1 example

This starter example keeps D1 focused on one job: answer a single query and prove the binding works locally.