1# Configuration
2 
3How to enable R2 Data Catalog and configure authentication.
4 
5## Prerequisites
6 
7- Cloudflare account with [R2 subscription](https://developers.cloudflare.com/r2/pricing/)
8- R2 bucket created
9- Access to Cloudflare dashboard or Wrangler CLI
10 
11## Enable Catalog on Bucket
12 
13Choose one method:
14 
15### Via Wrangler (Recommended)
16 
17```bash
18npx wrangler r2 bucket catalog enable <BUCKET_NAME>
19```
20 
21**Output:**
22```
23✅ Data Catalog enabled for bucket 'my-bucket'
24   Catalog URI: https://<account-id>.r2.cloudflarestorage.com/iceberg/my-bucket
25   Warehouse: my-bucket
26```
27 
28### Via Dashboard
29 
301. Navigate to **R2** → Select your bucket → **Settings** tab
312. Scroll to "R2 Data Catalog" section → Click **Enable**
323. Note the **Catalog URI** and **Warehouse name** shown
33 
34**Result:**
35- Catalog URI: `https://<account-id>.r2.cloudflarestorage.com/iceberg/<bucket-name>`
36- Warehouse: `<bucket-name>` (same as bucket name)
37 
38### Via API (Programmatic)
39 
40```bash
41curl -X POST \
42  "https://api.cloudflare.com/client/v4/accounts/<account-id>/r2/buckets/<bucket>/catalog" \
43  -H "Authorization: Bearer <api-token>" \
44  -H "Content-Type: application/json"
45```
46 
47**Response:**
48```json
49{
50  "result": {
51    "catalog_uri": "https://<account-id>.r2.cloudflarestorage.com/iceberg/<bucket>",
52    "warehouse": "<bucket>"
53  },
54  "success": true
55}
56```
57 
58## Check Catalog Status
59 
60```bash
61npx wrangler r2 bucket catalog status <BUCKET_NAME>
62```
63 
64**Output:**
65```
66Catalog Status: enabled
67Catalog URI: https://<account-id>.r2.cloudflarestorage.com/iceberg/my-bucket
68Warehouse: my-bucket
69```
70 
71## Disable Catalog (If Needed)
72 
73```bash
74npx wrangler r2 bucket catalog disable <BUCKET_NAME>
75```
76 
77⚠️ **Warning:** Disabling does NOT delete tables/data. Files remain in bucket. Metadata becomes inaccessible until re-enabled.
78 
79## API Token Creation
80 
81R2 Data Catalog requires API token with **both** R2 Storage + R2 Data Catalog permissions.
82 
83### Dashboard Method (Recommended)
84 
851. Go to **R2** → **Manage R2 API Tokens** → **Create API Token**
862. Select permission level:
87   - **Admin Read & Write** - Full catalog + storage access (read/write)
88   - **Admin Read only** - Read-only access (for query engines)
893. Copy token value immediately (shown only once)
90 
91**Permission groups included:**
92- `Workers R2 Data Catalog Write` (or Read)
93- `Workers R2 Storage Bucket Item Write` (or Read)
94 
95### API Method (Programmatic)
96 
97Use Cloudflare API to create tokens programmatically. Required permissions:
98- `Workers R2 Data Catalog Write` (or Read)
99- `Workers R2 Storage Bucket Item Write` (or Read)
100 
101## Client Configuration
102 
103### PyIceberg
104 
105```python
106from pyiceberg.catalog.rest import RestCatalog
107 
108catalog = RestCatalog(
109    name="my_catalog",
110    warehouse="<bucket-name>",           # Same as bucket name
111    uri="<catalog-uri>",                 # From enable command
112    token="<api-token>",                 # From token creation
113)
114```
115 
116**Full example with credentials:**
117```python
118import os
119from pyiceberg.catalog.rest import RestCatalog
120 
121# Store credentials in environment variables
122WAREHOUSE = os.getenv("R2_WAREHOUSE")      # e.g., "my-bucket"
123CATALOG_URI = os.getenv("R2_CATALOG_URI")  # e.g., "https://abc123.r2.cloudflarestorage.com/iceberg/my-bucket"
124TOKEN = os.getenv("R2_TOKEN")              # API token
125 
126catalog = RestCatalog(
127    name="r2_catalog",
128    warehouse=WAREHOUSE,
129    uri=CATALOG_URI,
130    token=TOKEN,
131)
132 
133# Test connection
134print(catalog.list_namespaces())
135```
136 
137### Spark / Trino / DuckDB
138 
139See [patterns.md](patterns.md) for integration examples with other query engines.
140 
141## Connection String Format
142 
143For quick reference:
144 
145```
146Catalog URI:  https://<account-id>.r2.cloudflarestorage.com/iceberg/<bucket>
147Warehouse:    <bucket-name>
148Token:        <r2-api-token>
149```
150 
151**Where to find values:**
152 
153| Value | Source |
154|-------|--------|
155| `<account-id>` | Dashboard URL or `wrangler whoami` |
156| `<bucket>` | R2 bucket name |
157| Catalog URI | Output from `wrangler r2 bucket catalog enable` |
158| Token | R2 API Token creation page |
159 
160## Security Best Practices
161 
1621. **Store tokens securely** - Use environment variables or secret managers, never hardcode
1632. **Use least privilege** - Read-only tokens for query engines, write tokens only where needed
1643. **Rotate tokens regularly** - Create new tokens, test, then revoke old ones
1654. **One token per application** - Easier to track and revoke if compromised
1665. **Monitor token usage** - Check R2 analytics for unexpected patterns
1676. **Bucket-scoped tokens** - Create tokens per bucket, not account-wide
168 
169## Environment Variables Pattern
170 
171```bash
172# .env (never commit)
173R2_CATALOG_URI=https://<account-id>.r2.cloudflarestorage.com/iceberg/<bucket>
174R2_WAREHOUSE=<bucket-name>
175R2_TOKEN=<api-token>
176```
177 
178```python
179import os
180from pyiceberg.catalog.rest import RestCatalog
181 
182catalog = RestCatalog(
183    name="r2",
184    uri=os.getenv("R2_CATALOG_URI"),
185    warehouse=os.getenv("R2_WAREHOUSE"),
186    token=os.getenv("R2_TOKEN"),
187)
188```
189 
190## Troubleshooting
191 
192| Problem | Solution |
193|---------|----------|
194| 404 "catalog not found" | Run `wrangler r2 bucket catalog enable <bucket>` |
195| 401 "unauthorized" | Check token has both Catalog + Storage permissions |
196| 403 on data files | Token needs both permission groups |
197 
198See [gotchas.md](gotchas.md) for detailed troubleshooting.
199