D1 bindings in cloudflare.config.ts

Quick configuration

import { bindings, defineConfig } from "cf/config";

export default defineConfig({
  worker: {
    name: "notes-worker",
    compatibilityDate: "2026-09-29",
    entrypoint: "./src/index.ts",
    env: {
      DB: bindings.d1({ name: "notes-db" }),
    },
  },
});

The binding key is DB, so Worker code accesses env.DB. notes-db identifies the database by name. The current helper also accepts id; use the actual database UUID if you want an explicit identifier.

Reference an existing database

import { bindings, defineConfig } from "cf/config";

export default defineConfig({
  worker: {
    name: "notes-worker",
    compatibilityDate: "2026-09-29",
    entrypoint: "./src/index.ts",
    env: {
      DB: bindings.d1({ id: "REPLACE_WITH_DATABASE_UUID" }),
    },
  },
});

Replace the placeholder before deployment. A binding declaration does not contain your table schema and does not apply SQL migrations.

Create and migrate deliberately

# Creates a remote database after authentication
cf d1 create --name notes-db

# Inspect flags and targets first
cf d1 migrations apply --help

# Replace the ID with the returned database UUID
cf d1 migrations apply DATABASE_UUID --dir migrations --local

For this beta, the migration command requires a database ID. The name or DB binding is not interchangeable with that positional argument. Removing --local targets the remote database; do so only after reviewing the SQL and the selected account.

Local development uses simulated data separate from the remote database. Verify the state directory used by your development and migration commands. Passing a different persistence directory can make a populated local database appear empty.

From Wrangler configuration

Wrangler separates binding, database_name and database_id inside d1_databases. In the new format, the object key supplies the binding name and bindings.d1 carries the resource reference. Let cf migrate perform the source conversion, then inspect these identities.

Common mistakes

• Using a database name in the migration command that requires an ID.
• Running remote migrations when you intended to seed local state.
• Changing the binding key without updating env.DB references in application code.
• Treating a successful Worker deployment as proof that required tables exist.

Return to the configuration guide to combine D1 with other bindings, or use the builder for a typed starting point.