Setting the file. One moment.
Chapter 04 · Cloudflare Deploy
Subchapter 4.164
references/r2-sql/configuration.mdMarkdown4 KBView on GitHub
R2 SQL queries Apache Iceberg tables in R2 Data Catalog. Must enable catalog on bucket first.
npx wrangler r2 bucket catalog enable <bucket-name>Output includes:
Example output:
Catalog enabled successfully
Warehouse: my-bucket
Catalog URI: https://abc123.r2.cloudflarestorage.com/iceberg/my-bucketImportant: Enabling catalog creates metadata directories in bucket but does not modify existing objects.
R2 SQL requires API token with R2 permissions.
R2 Admin Read & Write (includes R2 SQL Read permission)
| Permission | Grants Access To |
|---|---|
| R2 Admin Read & Write | R2 storage operations + R2 SQL queries + Data Catalog operations |
| R2 SQL Read | SQL queries only (no storage writes) |
Note: R2 SQL Read permission not yet available via Dashboard - use Admin Read & Write.
Set environment variable for Wrangler to use:
export WRANGLER_R2_SQL_AUTH_TOKEN=<your-token>Or create .env file in project directory:
WRANGLER_R2_SQL_AUTH_TOKEN=<your-token>Wrangler automatically loads .env file when running commands.
For programmatic access (non-Wrangler), pass token in Authorization header:
curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/sql/query \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{
"warehouse": "my-bucket",
"query": "SELECT * FROM default.my_table LIMIT 10"
}'Note: HTTP API endpoint URL may vary - see patterns.md for current endpoint.
Test configuration by querying system tables:
# List namespaces
npx wrangler r2 sql query "my-bucket" "SHOW DATABASES"
# List tables in namespace
npx wrangler r2 sql query "my-bucket" "SHOW TABLES IN default"If successful, returns JSON array of results.
Cause: Invalid or missing token
Solution:
WRANGLER_R2_SQL_AUTH_TOKEN environment variable setCause: Data Catalog not enabled
Solution:
npx wrangler r2 bucket catalog enable <bucket-name>Cause: Token lacks required permissions
Solution: