Skip to content

docs(limits): document the statement limits, and warn before a table hits one - #397

Merged
prisis merged 3 commits into
alphafrom
docs/cloudflare-statement-limits
Aug 10, 2026
Merged

prisis merged 3 commits into
alphafrom
docs/cloudflare-statement-limits

Conversation

@prisis

@prisis prisis commented Aug 10, 2026

Copy link
Copy Markdown
Member

Follow-up to #396. That PR fixed the code against Workerd's SQLite limits; this one makes the limits visible — in the docs you read while designing a schema, and in the Studio while you still have runway.

The docs page had none of them

apps/docs/src/content/docs/limits.mdx — "Cloudflare ceilings you should keep in your head" — listed the ceilings you plan capacity against (DO storage, req/s, bundle size) and not one of the per-statement limits that turn a working app into a runtime error as its schema grows.

Those are the interesting ones precisely because they are unintuitive: they are set by the Workers runtime rather than by SQLite, they sit far below SQLite's own defaults, and D1 inherits them because it runs the same build.

Limit Workerd Stock SQLite
Terms in a compound SELECT 5 500
Bound parameters 100 500,000
LIKE pattern 50 bytes 50,000
Columns per table 100 2,000
Row / string / BLOB 2 MB 1 GB
SQL statement text 100 KB 1 GB
Expression depth 100 1,000

The page now says which of these the generated SQL absorbs on your behalf and which two are yours to design around — "we handle it" and "you cannot do this" are very different pieces of advice, and a table alone does not distinguish them.

Also adds Queues, Workers KV, and Workflows sections. All three are shipped surfaces (ctx.queues, ctx.kv, ctx.workflows) whose limits shape how you use them, and none had an entry.

One row was wrong

Dropped Storage tx | 128 KB / op | Batch large writes via ctx.db.insertMany. That is the value ceiling for a KV-backed Durable Object; Lunora's are SQLite-backed, where the equivalent ceiling is the 2 MB row now documented above. Its advice also pointed at insertMany, which does nothing for a per-value cap.

Warning before the ceiling, not at it

D1 caps a table at 100 columns, and a .global() table is provisioned column-per-declared-field. #396 made that failure raise a clear error instead of a bare "too many columns" — but it still raises at provisioning time, on the first request after deploy, and the remediation is a design change: split the table, or collapse the tail of its fields into one object field. That is not advice you want on the commit that breaks the app.

global_table_near_column_limit fires at 90 columns, leaving ten fields of runway, and surfaces in the Studio's Advisors pages alongside the rest of the schema lints — no new page, route, or RPC, because that surface already exists.

Shard-local tables are exempt by construction: their fields live in a single JSON document, so no field count can breach a column limit.

What this deliberately does not cover

A static lint only answers "am I near a limit?" for limits visible in the schema. The runtime ones — how close a document is to 2 MB, actual DO SQLite size — need measured data; the advisor already has that seam (hot_shard consumes context.shardTraffic from the Studio backend), so those would be a feeder plus a lint rather than new UI. The per-statement limits are not observable at rest at all: they exist only while a statement is being built, which is why they are handled in the SQL builder.

Testing

Three cases on the new lint: the threshold boundary either side (89 columns silent, 90 flagged), and a 200-field shard-local table staying silent. Advisor suite green at 470.

🤖 Generated with Claude Code

https://claude.ai/code/session_011sk9BLaUZDkPVAZ1sKhuDP

prisis and others added 2 commits August 10, 2026 13:41
The Limits page listed the ceilings you plan capacity against — DO storage,
req/s, bundle size — but none of the per-statement ones, which are the limits
that turn a working app into a runtime error as its schema grows. Those are set
by the Workers runtime rather than by SQLite, sit far below SQLite's own
defaults, and apply to D1 identically because it runs the same build: 5 terms in
a compound SELECT, 100 bound parameters, a 50-byte LIKE pattern, 100 columns per
table, a 2 MB row, 100 KB of statement text, expression depth 100.

Says which ones the generated SQL absorbs on your behalf and which two are
yours to design around, since "we handle it" and "you cannot do this" are very
different pieces of advice and the table alone does not distinguish them.

Also adds Queues, Workers KV, and Workflows sections — all three are shipped
surfaces (`ctx.queues`, `ctx.kv`, `ctx.workflows`) whose limits shape how you
use them, and none had an entry.

Drops the "Storage tx / 128 KB per op" row: that is the value ceiling for a
KV-backed Durable Object, and Lunora's are SQLite-backed, where the equivalent
ceiling is the 2 MB row now documented above. Its advice pointed at
`insertMany`, which does not help with a per-value cap.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011sk9BLaUZDkPVAZ1sKhuDP
D1 caps a table at 100 columns, and a `.global()` table is provisioned
column-per-declared-field. Past the ceiling the store now raises a clear error,
but it raises it at provisioning time — on the first request after deploy — and
the remediation is a design change: split the table, or collapse the tail of its
fields into one object field. That is not advice you want on the commit that
breaks the app.

`global_table_near_column_limit` fires at 90 columns, leaving ten fields of
runway, and surfaces in the Studio's Advisors pages with the rest of the schema
lints. Shard-local tables are exempt by construction — their fields live in one
JSON document, so no field count can breach a column limit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011sk9BLaUZDkPVAZ1sKhuDP
@netlify

netlify Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for lunorash ready!

Name Link
🔨 Latest commit de1e0a1
🔍 Latest deploy log https://app.netlify.com/projects/lunorash/deploys/6a79ba395f44bd0008e9ed71
😎 Deploy Preview https://deploy-preview-397--lunorash.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

@prisis, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 11 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c2f3c72a-109e-4090-a9d0-f8fa86cfe7e9

📥 Commits

Reviewing files that changed from the base of the PR and between 1c45d6d and de1e0a1.

⛔ Files ignored due to path filters (2)
  • api-snapshots/advisor.api.md is excluded by none and included by none
  • packages/advisor/__tests__/static-lints.test.ts is excluded by !**/__tests__/**, !**/*.test.ts and included by packages/**
📒 Files selected for processing (3)
  • apps/docs/src/content/docs/limits.mdx
  • packages/advisor/src/index.ts
  • packages/advisor/src/lints/static/global-table-near-column-limit.ts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for following the naming conventions! 🙏

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for confirming the Contributor License Agreement! 🙏

@prisis
prisis merged commit 424b60d into alpha Aug 10, 2026
41 checks passed
@prisis
prisis deleted the docs/cloudflare-statement-limits branch August 10, 2026 11:59
@codspeed

codspeed Bot commented Aug 10, 2026

Copy link
Copy Markdown

Merging this PR will degrade performance by 10.29%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 1 regressed benchmark
✅ 252 untouched benchmarks
⏩ 10 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ flat 3 primitives (the notify.send attribute shape) 55.7 µs 62.1 µs -10.29%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing docs/cloudflare-statement-limits (de1e0a1) with alpha (2c0a3e6)2

Open in CodSpeed

Footnotes

  1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

  2. No successful run was found on alpha (1c45d6d) during the generation of this report, so 2c0a3e6 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.16%. Comparing base (95d33d6) to head (de1e0a1).
⚠️ Report is 205 commits behind head on alpha.

Additional details and impacted files
@@            Coverage Diff             @@
##            alpha     #397      +/-   ##
==========================================
+ Coverage   87.09%   87.16%   +0.06%     
==========================================
  Files        1172     1182      +10     
  Lines       63383    64110     +727     
  Branches    15447    15786     +339     
==========================================
+ Hits        55202    55880     +678     
- Misses       7654     7704      +50     
+ Partials      527      526       -1     
Files with missing lines Coverage Δ
packages/advisor/src/index.ts 100.00% <ø> (ø)
...src/lints/static/global-table-near-column-limit.ts 100.00% <100.00%> (ø)

... and 10 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using our GitHub Discussions tab for questions.

@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Sep 9, 2026

This branch was previously deployed

1 inactive deployment
benchmarks — de1e0a1e Deployed Aug 10, 2026 by prisis via Benchmarks #1649
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants