[vince-gonzalez]

What this changes

Adds one paragraph to the Batch limits note on the D1 limits page, stating that a db.batch() counts as a single query against Queries per Worker invocation, rather than one query per statement.

Why

The note immediately above says:

Limits for individual queries (listed above) apply to each individual statement contained within a batch statement. For example, the maximum SQL statement length of 100 KB applies to each statement inside a db.batch().

Queries per Worker invocation is listed above that note, so the sentence reads as though it applies — but it does not. /d1/worker-api/d1-database/ does not mention per-invocation limits either, so a reader currently cannot determine whether a 2,000-statement batch costs 1 query or 2,000 against a documented budget of 1,000.

In practice this leads people to chunk bulk inserts to keep the statement count under 1,000, which is not necessary.

How I checked

Against a live D1 database (region ENAM, Workers Paid), from inside a deployed Worker, one fresh invocation per measurement, using SELECT 1 so a count limit would bite before any duration limit.

The documented figure is exact. It is enforced on the 1,001st query, and the first 1,000 complete:

queries requested	completed	result
999	999	ok
1,000	1,000	ok
1,001	1,000	Too many API requests by single Worker invocation
2,000	1,000	Too many API requests by single Worker invocation

A batch is counted differently. Both of these are above the same documented budget, in the same shape of invocation:

form	result
2,000 queries, issued one at a time	refused after exactly 1,000
2,000 statements in one db.batch()	ok, 421 ms

A single batch() call also completed with 150,000 statements, which is 150x the per-invocation budget.

Scope

The change only states how a batch is counted. It deliberately does not claim anything about:

• which limit stops a very large batch — refusal begins between 150,000 and 175,000 statements at one row shape, but I did not isolate the cause, and at least three ~30-second ceilings are plausible there
• the Free plan figure of 50, which I had no way to test
• any statement-count ceiling on batch()

No existing text is altered and no documented number is disputed. The 1,000 figure is correct as written.

Method and raw data: https://github.com/vince-gonzalez/d1bench

[cloudflare-docs-bot]

AI Review

✅ Reviewed 763f04c · 0 findings · incremental

Commands

• /review Run a review now.
• /full-review Review the entire PR diff.
• /disable-auto-review Stop automatic reviews.
• /rebase Rebase against production.