cloudflare-d1-database

name	cloudflare-d1-database
description	Use when building, reviewing, or maintaining Cloudflare D1 persistence for Workers, Pages Functions, edge apps, Wrangler migrations, bindings, and edge-compatible relational storage.

Cloudflare D1 Database

Use Cloudflare D1 when a Cloudflare Workers or Pages Functions app needs relational persistence through Cloudflare platform bindings.

Pair With

• database-profile-selector when choosing D1.
• deployment-target-selector and cloudflare-edge-hosting.
• hono-backend, sveltekit-fullstack, nuxt-fullstack, or the existing framework skill when D1 is accessed by edge handlers.

Good Fit

• Cloudflare Workers/Pages apps needing small to moderate relational storage.
• Edge-first APIs, webhooks, lightweight apps, and previewable deployments that already use Wrangler and Cloudflare bindings.
• Projects that accept platform-specific D1 constraints and migration workflow.

Poor Fit

• Non-Cloudflare runtimes.
• Heavy relational workloads, high-write workloads, or workloads requiring broad PostgreSQL features, extensions, LISTEN/NOTIFY, or direct TCP access.
• Apps without a clear binding, migration, environment, and backup plan.

Contract Checklist

database_profile:
  target: "cloudflare-d1"
  decision_source: "user | docs | detected | project-overlay | recommended-fallback | blocked"
  evidence: []
  data_scope: "edge-app"
  consistency: "globally-distributed | relational | unknown"
  access_pattern: "edge-binding"
  migration_strategy: ""
  backup_restore: ""
  required_skills:
    - "database-profile-selector"
    - "cloudflare-d1-database"
    - "cloudflare-edge-hosting"
  verification:
    schema_check: ""
    migration_check: ""
    integration_test: ""
    runtime_smoke: ""
  non_goals:
    - "do not migrate database unless explicitly requested"

Defaults

• Keep D1 bindings explicit in environment and framework types.
• Keep migrations in the repository and test them against local and remote environments when possible.
• Keep edge runtime constraints visible in the Task Contract.
• Avoid raw Node-only database clients in D1 handlers.

Verification

• Wrangler/local migration check.
• Typecheck for bindings and runtime environment.
• Integration or route tests that exercise D1 reads/writes.
• Local preview or deployed Worker/Pages runtime smoke.

Block Instead of Defaulting

Block when the project is not targeting Cloudflare, when bindings/account access are missing, or when data scale/consistency/backup requirements exceed D1 fit.