Description

Please add a connection driver for Cloudflare R2 SQL.

R2 SQL is Cloudflare's serverless, distributed analytics query engine for running SQL against Apache Iceberg tables managed by R2 Data Catalog (i.e. querying data that lives directly in an R2 bucket, no separate warehouse to provision). It went into open beta in September 2025 and has been expanding quickly (JOINs, subqueries, CTEs, and 190+ scalar/aggregate functions have landed since).

Note: this is not the same as the existing Cloudflare D1 requests (#3191, #3588, #3346, #3307). D1 is a serverless SQLite database; R2 SQL is a read-only query engine over Iceberg tables in object storage. They're different products with different endpoints and semantics.

Today the only ways to run R2 SQL are the wrangler r2 sql query CLI or a raw HTTP call. There is no GUI client, which is exactly the gap TablePlus fills for every other engine it supports.

What a driver would need to talk to

R2 SQL exposes a single REST endpoint. A query is a POST with a JSON body, authenticated with a bearer token:

POST https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/r2-sql/query/{BUCKET_NAME}
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "query": "SELECT * FROM namespace.table_name LIMIT 10;"
}

Reference curl from the docs:

curl -X POST \
  "https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/r2-sql/query/{BUCKET_NAME}" \
  -H "Authorization: Bearer ${WRANGLER_R2_SQL_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "query": "SELECT * FROM namespace.table_name limit 10;" }'

Connection parameters a driver would expose

• Account ID — Cloudflare account ID (part of the endpoint path).
• Bucket name — the R2 bucket whose Data Catalog is being queried (part of the endpoint path).
• Warehouse name — associated with the catalog; retrievable via wrangler r2 bucket catalog get <BUCKET_NAME> or in the dashboard under R2 → bucket → Settings → R2 Data Catalog → Warehouse name.
• API token — a Cloudflare API token, sent as Authorization: Bearer <token>.

Authentication

Auth is a Cloudflare API token (bearer), not username/password. The token needs three permission groups:

• R2 SQL — read-only (Workers R2 SQL Read)
• R2 Data Catalog — read (Workers R2 Data Catalog Write per the docs' example policy)
• R2 Storage — read/write (Workers R2 Storage Write), needed to read the underlying data files

The wrangler CLI reads this token from the WRANGLER_R2_SQL_AUTH_TOKEN environment variable; over HTTP it goes in the Authorization header.

SQL surface

R2 SQL is read-only / retrieval only — SELECT queries against Iceberg tables, no INSERT/UPDATE/DELETE/DDL. That keeps the driver scope small: a TablePlus connection could reasonably be read-only (browse namespaces/tables, run SELECT, view results), with no row-editing/write path required. Currently supported grammar includes SELECT, WHERE, LIMIT, column aliases, CASE, aggregates (incl. exact and approximate variants like approx_distinct), JOINs (INNER/LEFT/RIGHT/FULL/CROSS + implicit), subqueries, CTEs, and struct/array/map access. EXPLAIN is supported for inspecting the query plan.

Nice-to-haves (not required for a first version)

• Schema browser populated from the Iceberg namespaces/tables in the catalog.
• Read the token from WRANGLER_R2_SQL_AUTH_TOKEN if present, matching the CLI's convention.
• Mark the connection read-only in the UI so the editor grid doesn't offer writes that the engine will reject.

Documentation

• R2 SQL overview: https://developers.cloudflare.com/r2-sql/
• Query data (Wrangler + HTTP API + auth): https://developers.cloudflare.com/r2-sql/query-data/
• SQL reference: https://developers.cloudflare.com/r2-sql/sql-reference/
• Getting started: https://developers.cloudflare.com/r2-sql/get-started/
• Limitations & best practices: https://developers.cloudflare.com/r2-sql/reference/limitations-best-practices/
• Machine-readable docs index: https://developers.cloudflare.com/r2-sql/llms.txt

Why this feature/change is important?

• R2 Data Catalog + R2 SQL turns an R2 bucket into a queryable Iceberg lakehouse, and adoption is growing fast — but there is currently no GUI client for it. Users are stuck on the CLI or hand-written curl.
• TablePlus is already the natural home for this: there's clear existing demand for Cloudflare data products in this tracker (the D1 requests), and R2 SQL is arguably a better fit because it speaks a single, well-documented HTTP+JSON query endpoint.
• The read-only nature keeps the implementation contained — no write/commit path, no transaction handling — so it's a comparatively low-surface-area driver relative to a full RDBMS.
• It's a standard bearer-token REST API with a { "query": "..." } body, which maps cleanly onto TablePlus's existing "run SQL, render a result grid" model.