Cloudflare R2 SQL Query Support in VS Code

Overview

R2 SQL is Cloudflare’s serverless, distributed query engine for Apache Iceberg tables stored in R2 Data Catalog. DBCode connects directly to the R2 SQL API, so you can explore and query your data lake without exporting it to an external warehouse.

• Serverless queries: SQL runs on Cloudflare’s network next to your R2 storage; DBCode streams back the results
• Schema browsing: namespaces, tables, and Iceberg column types in the object tree, fetched from the free catalog API
• EXPLAIN visualization: graphical query plans via R2 SQL’s EXPLAIN FORMAT JSON
• Read-only by design: R2 SQL is a query engine; data is written by Pipelines or other Iceberg engines

API Token Authentication

Create an R2 API token with Admin Read only (or Admin Read & Write) permissions, which covers both R2 Data Catalog and R2 SQL reads:

1. In the Cloudflare dashboard, go to R2 object storage
2. Under Account Details, select Manage next to API Tokens
3. Create an Account API token with Admin Read only permission
4. Copy the token value

Connecting

1. Open the DBCode Extension: Launch Visual Studio Code and open the DBCode extension.
2. Add a New Connection: Click on the “Add Connection” icon.
3. Complete connection form:
   • Select Cloudflare R2 SQL as the database type
   • Enter your API token, then pick your account from the dropdown
   • Optionally pick a catalog-enabled bucket from the dropdown, or leave it blank to see every catalog-enabled bucket in the account
4. Connect: Click save to establish your connection.
5. Start Querying: Query your Iceberg tables with SQL, for example SELECT * FROM default.my_table LIMIT 100.

The connection covers your whole account: every catalog-enabled bucket appears underneath it as a database. You can also reach the same connection through the Cloudflare cloud provider.

For detailed instructions on connecting, refer to the Connect article.

For more information about R2 SQL, check out Cloudflare’s documentation.