1# R2 SQL Configuration
2 
3Setup and configuration for R2 SQL queries.
4 
5## Prerequisites
6 
7- R2 bucket with Data Catalog enabled
8- API token with R2 permissions
9- Wrangler CLI installed (for CLI queries)
10 
11## Enable R2 Data Catalog
12 
13R2 SQL queries Apache Iceberg tables in R2 Data Catalog. Must enable catalog on bucket first.
14 
15### Via Wrangler CLI
16 
17```bash
18npx wrangler r2 bucket catalog enable <bucket-name>
19```
20 
21Output includes:
22- **Warehouse name** - Typically same as bucket name
23- **Catalog URI** - REST endpoint for catalog operations
24 
25Example output:
26```
27Catalog enabled successfully
28Warehouse: my-bucket
29Catalog URI: https://abc123.r2.cloudflarestorage.com/iceberg/my-bucket
30```
31 
32### Via Dashboard
33 
341. Navigate to **R2 Object Storage** → Select your bucket
352. Click **Settings** tab
363. Scroll to **R2 Data Catalog** section
374. Click **Enable**
385. Note the **Catalog URI** and **Warehouse** name
39 
40**Important:** Enabling catalog creates metadata directories in bucket but does not modify existing objects.
41 
42## Create API Token
43 
44R2 SQL requires API token with R2 permissions.
45 
46### Required Permission
47 
48**R2 Admin Read & Write** (includes R2 SQL Read permission)
49 
50### Via Dashboard
51 
521. Navigate to **R2 Object Storage**
532. Click **Manage API tokens** (top right)
543. Click **Create API token**
554. Select **Admin Read & Write** permission
565. Click **Create API Token**
576. **Copy token value** - shown only once
58 
59### Permission Scope
60 
61| Permission | Grants Access To |
62|------------|------------------|
63| R2 Admin Read & Write | R2 storage operations + R2 SQL queries + Data Catalog operations |
64| R2 SQL Read | SQL queries only (no storage writes) |
65 
66**Note:** R2 SQL Read permission not yet available via Dashboard - use Admin Read & Write.
67 
68## Configure Environment
69 
70### Wrangler CLI
71 
72Set environment variable for Wrangler to use:
73 
74```bash
75export WRANGLER_R2_SQL_AUTH_TOKEN=<your-token>
76```
77 
78Or create `.env` file in project directory:
79 
80```
81WRANGLER_R2_SQL_AUTH_TOKEN=<your-token>
82```
83 
84Wrangler automatically loads `.env` file when running commands.
85 
86### HTTP API
87 
88For programmatic access (non-Wrangler), pass token in Authorization header:
89 
90```bash
91curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/r2/sql/query \
92  -H "Authorization: Bearer <your-token>" \
93  -H "Content-Type: application/json" \
94  -d '{
95    "warehouse": "my-bucket",
96    "query": "SELECT * FROM default.my_table LIMIT 10"
97  }'
98```
99 
100**Note:** HTTP API endpoint URL may vary - see [patterns.md](patterns.md#http-api-query) for current endpoint.
101 
102## Verify Setup
103 
104Test configuration by querying system tables:
105 
106```bash
107# List namespaces
108npx wrangler r2 sql query "my-bucket" "SHOW DATABASES"
109 
110# List tables in namespace
111npx wrangler r2 sql query "my-bucket" "SHOW TABLES IN default"
112```
113 
114If successful, returns JSON array of results.
115 
116## Troubleshooting
117 
118### "Token authentication failed"
119 
120**Cause:** Invalid or missing token
121 
122**Solution:**
123- Verify `WRANGLER_R2_SQL_AUTH_TOKEN` environment variable set
124- Check token has Admin Read & Write permission
125- Create new token if expired
126 
127### "Catalog not enabled on bucket"
128 
129**Cause:** Data Catalog not enabled
130 
131**Solution:**
132- Run `npx wrangler r2 bucket catalog enable <bucket-name>`
133- Or enable via Dashboard (R2 → bucket → Settings → R2 Data Catalog)
134 
135### "Permission denied"
136 
137**Cause:** Token lacks required permissions
138 
139**Solution:**
140- Verify token has **Admin Read & Write** permission
141- Create new token with correct permissions
142 
143## See Also
144 
145- [r2-data-catalog/configuration.md](../r2-data-catalog/configuration.md) - Detailed token setup and PyIceberg connection
146- [patterns.md](patterns.md) - Query examples using configuration
147- [gotchas.md](gotchas.md) - Common configuration errors
148