Cloudflare D1 App¶

Status: Authored

Cloudflare Workers or Pages Functions using D1 with versioned SQL migrations and environment-specific bindings.

Full rubric¶

Cloudflare D1 App v1

Reference implementation¶

Reference template map¶

What this teaches¶

Choose this stack when a Cloudflare runtime owns a SQL database and the schema has to change over time without losing data. The interesting part is not writing D1 queries - Cloudflare documents that - it is that a database is the one part of a deploy you cannot roll back by redeploying the previous artifact. Code is replaceable; applied schema is not.

Everything this standard judges follows from that asymmetry. Migrations are append-only once a shared environment has applied them, because editing an applied file makes source history and database history disagree with no way to detect it later - hence a checksum manifest or equivalent drift guard. Migrations must be proved to apply to a clean database in CI, because the only environment where an untested migration is cheap is a disposable one. Environments must be distinct databases, because a single shared database turns a preview experiment into a production incident. Tenant isolation must be a declared model rather than an assumption, because "we always pass the tenant id" is not a control. And deploy ordering must be explicit, because a release whose code expects a column that has not landed fails in the least recoverable place.

Do not choose this stack for generic SQL style guidance, for non-Cloudflare databases, or for a repo that merely reads a D1 binding it does not own the schema of.

Decision matrix¶

Upstream references¶

Cloudflare owns D1 and Wrangler doctrine; VCQA owns the migration, drift, isolation, and deploy-ordering glue that no single upstream page covers.

• Cloudflare D1 documentation
• D1 migrations
• D1 prepared statement methods
• D1 environments
• D1 local development
• D1 Time Travel and backups
• D1 import and export data
• Wrangler D1 commands
• Pages Functions bindings
• GitHub Actions secure use
• OWASP Top 10

Scope¶

Cloudflare Workers or Pages Functions using D1 with versioned SQL migrations and environment-specific bindings.

Not in scope¶

• generic SQL style
• non-Cloudflare database deployments
• frontend state management

Composes¶

• Cloudflare D1
• Cloudflare Workers
• Cloudflare Pages Functions
• TypeScript
• Web Security
• GitHub Actions

VCQA-owned rule surface¶

• append-only/versioned migrations.
• migration checksum or drift guard.
• local apply test.
• staging/prod/tenant database isolation.
• parameterized query enforcement.

Detection signals¶

• [[d1_databases]] in Wrangler config
• migrations/*.sql
• D1 binding usage in app code

Combination-born guidelines¶

• Migrations are append-only after deployment; editing applied migrations is a defect.
• CI applies migrations to a clean local database before production deployment.
• Tenant, staging, preview, and production databases need distinct binding boundaries.

Rule highlights¶

• R-SHAPE-1: The runtime boundary is Cloudflare-owned. D1 access belongs in Workers, Pages Functions, or server code compiled to those runtimes, never in browser code.
• R-BIND-1: Binding names are stable and typed at the boundary. D1 bindings should be represented in generated Cloudflare types or explicit Env/Bindings interfaces.
• R-MIG-1: Migrations are append-only after shared apply. A migration that may have reached preview, staging, production, or a tenant database is changed only by a later migration.
• R-MIG-3: Clean local migration apply is a required gate. CI applies all migrations to a clean local D1 database before remote promotion.
• R-DRIFT-1: Applied migration identity is drift-checked. A checksum manifest, protected migration history, or equivalent guard proves source history still matches applied database history.
• R-ENV-1: Local, preview/staging, and production use distinct databases. Wrangler and Pages bindings must make the target database explicit.
• R-TENANT-1: Tenant isolation model is declared and enforced. Multi-tenant apps choose per-tenant database, per-tenant binding/service boundary, or shared database with mandatory row/table scoping.
• R-SQL-1: Untrusted values use prepared statement binding. Request data, auth claims, route params, and tenant IDs enter SQL through .bind(...), not interpolation.
• R-CI-2: Production migrations run before production code deploy. Deploy ordering must match the schema expectations of the release, with documented exceptions for staged rollouts.
• R-DEPLOY-1: Preview deploys do not run production migrations. Pull request and preview workflows use preview/staging databases only.

Limitations¶

• Append-only is judged from repository history. VCQA can see that a migration file changed after it was added; it cannot see which databases had already applied it. A repo that rewrites history, or squashes, can hide a real violation.
• Drift is checked against a manifest, not against the live database. The guard proves source history is internally consistent. Only a query against the deployed database proves the database agrees, and a repository scan does not connect to one.
• Environment isolation is judged from declared config. Databases created and bound through the Cloudflare dashboard rather than in Wrangler config cannot be seen, so the check falls back to evidence-only.
• Tenant isolation is judged as a declared model plus its enforcement points. A shared database with row scoping can satisfy the rule and still leak if one query forgets the predicate; the rubric asks for enforcement you can point at, not a proof of correctness.
• Query safety detection is pattern-based. Prepared-statement binding is detectable; SQL assembled through several helpers before reaching D1 may need human review.
• Backup and restore posture is out of scope for v1. Time Travel and export are cited as upstream references, not judged as rules.

Anti-patterns¶

• Editing a migration after it has been applied to staging or production.
• Reusing one D1 database for preview, staging, and production.
• Building SQL strings with request data.
• Running production migrations from a local laptop with no CI gate.
• Leaving tenant isolation as an implementation assumption instead of a documented model.

Benefits¶

• Cloudflare SaaS example D1 usage.

Maintenance¶

Editions are cut on material change, not on a calendar. A review that finds the edition still correct moves Last reviewed forward without a new edition. Metadata lives in standards/registry.json.

Independent Assessment¶

• Cloudflare D1 App stack page assessment