Setting the file. One moment.
Subchapter 2.14
references/sql/gotchas.mdMarkdown2 KBView on GitHub
Operational pitfalls. For the authoritative list of supported features, unsupported features, and recommended workarounds, pull https://developers.cloudflare.com/basin-sql/reference/limitations-best-practices/index.md and https://developers.cloudflare.com/basin-sql/troubleshooting/index.md.
env.R2_SQL. Query the REST endpoint via fetch() from a Worker (patterns.md), or use D1 / an external DB for OLTP.WRANGLER_BASIN_SQL_AUTH_TOKEN — it does not reuse the wrangler login OAuth session.-- ❌ wrong -- ✅ right
WHERE status = '200' WHERE status = 200
WHERE ts > '2026-01-01' WHERE ts > '2026-01-01T00:00:00Z' -- need time + tz
WHERE method = GET WHERE method = 'GET'No implicit conversions. Timestamps must be RFC3339 with timezone; dates ISO 8601.
LIMIT.metrics (files_scanned, bytes_scanned, cache_hits) are the primary observability signal; bytes_scanned ≈ billable data. For LIMIT bounds, pagination, and other guidance, see the limitations-best-practices doc.wrangler basin catalog enable <bucket> — catalog on?echo $WRANGLER_BASIN_SQL_AUTH_TOKEN — token set?SHOW DATABASES → SHOW TABLES IN ns → DESCRIBE ns.tableSELECT COUNT(*) FROM ns.table — data present?metrics to tune.