topic hub
Cloudflare D1 knowledge
Public KFA evidence about Cloudflare D1 schemas, queries, migrations, and operational behavior.
Common Problems
- How should a D1 timeout with an uncertain write result be reconciled?
## Question How should a D1 timeout with an uncertain write result be reconciled? ## Why this matters Recurring public developer task for Cloudflare D1. ## Environment / product Cloudflare D1 ## What needs to be determined Current researched guidance, applicability, limitations, and primary sources for this question. R
- [Cloudflare D1] 'D1_ERROR: too many SQL variables at offset N' from ORM bulk inserts/IN lists (100 bound parameter limit)
Cause (Documented platform behavior): D1 limits bound parameters to 100 per query (applies to each statement in a batch), lower than stock SQLite limits ORMs assume. Fix status: documented_behavior (fixed in Prisma issue milestone 5.15.0 (chunking for D1 adapter; exact fix details not read)) Limitations: - Drizzle issu
- How can local and remote D1 databases be distinguished before a migration?
Recurring Cloudflare D1 research question: How can local and remote D1 databases be distinguished before a migration?
- How should D1 migrations be applied safely across staging and production?
Recurring Cloudflare D1 research question: How should D1 migrations be applied safely across staging and production?
- What happens when one statement in a D1 batch transaction fails?
Recurring Cloudflare D1 research question: What happens when one statement in a D1 batch transaction fails?
- How should D1 read replication and session bookmarks preserve read-after-write consistency?
## Question How should D1 read replication and session bookmarks preserve read-after-write consistency? ## Why this matters Recurring public developer task for Cloudflare D1. ## Environment / product Cloudflare D1 ## What needs to be determined Current researched guidance, applicability, limitations, and primary source
Solutions with evidence
- Researched guidance: How can local and remote D1 databases be distinguished before a migration?
Before applying a D1 migration, make the target explicit and use the same flag for the read-only check and apply: `wrangler d1 migrations list DB --local` then `wrangler d1 migrations apply DB --local` for Wrangler's local database; use `--remote` for the Cloudflare database; use `--preview` for a preview D1 database.
- Researched guidance: What happens when one statement in a D1 batch transaction fails?
For Cloudflare D1's Worker Binding API, db.batch([...prepared statements]) is a single SQL transaction: statements execute sequentially and non-concurrently. If any statement fails, D1 returns an error for that statement and aborts/rolls back the entire batch, so writes made earlier in that same batch must not be treat
- Proposed fix: [Cloudflare D1] 'D1_ERROR: too many SQL variables at offset N' from ORM bulk inserts/IN lists (100 bound parameter limit)
Recommended action: Chunk inserts/IN lists so each statement has <=100 bound parameters; use db.batch of smaller statements; upgrade Prisma to a release with D1-aware chunking. Option: Chunk statements to <=100 parameters [evidence: official_recommended_action] Applies when: Bulk inserts, IN lists Steps: 1. rowsPerChun
- Researched guidance: How should D1 migrations be applied safely across staging and production?
Research delta for a staged D1 promotion workflow: define separate named Wrangler environments with separate D1 database IDs, e.g. env.staging.d1_databases and env.production.d1_databases; D1 bindings are non-inheritable, so each environment must be explicit. The current Wrangler command reference lists the global --en