Basin

From the author

Build and troubleshoot Cloudflare Basin analytics workflows with Basin Pipelines, Basin Catalog, and Basin SQL. Use for streaming data into R2 Iceberg tables, managing catalogs, or querying those tables; also use for requests using the former Data Platform, Pipelines, R2 Data Catalog, or R2 SQL names.

— the description by Cloudflare

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Basin is a suite of tools for ingesting, transforming, and querying data using Apache Iceberg tables stored in Cloudflare R2. It comprises three main components: Basin Pipelines for event ingestion and transformation, Basin Catalog for managing Iceberg metadata and table maintenance, and Basin SQL for performing analytical queries. This skill provides guidance on setting up these components, configuring connections for engines like Spark or Python, and troubleshooting common operational issues.

What it does

Stream events and transform data rows for delivery to R2 storage.
Manage Iceberg table metadata, maintenance tasks, and engine access.
Execute analytical SQL queries against Iceberg tables.
Configure and authenticate connections for Basin Pipelines, Catalog, and SQL.
Provide guidance on using Wrangler commands for Basin resource management.

When to use it

When setting up new data ingestion pipelines that target R2 storage.
When you need to manage Iceberg table metadata or perform table maintenance.
When querying large datasets stored in R2 using analytical SQL.
When migrating from legacy Cloudflare Data Platform or R2 Data Catalog workflows.

Advantages

Unified management of data ingestion, cataloging, and querying.
Native integration with Cloudflare R2 and Apache Iceberg standards.
Supports standard analytical SQL for querying object storage data.
Provides clear paths for both control-plane administration and engine-specific operations.

Usage examples

“How do I set up a new Basin Pipeline to ingest events into R2?”: The agent will guide you through the Basin Pipelines configuration, including defining event transformations and setting up the delivery destination in R2.
“What are the steps to connect PyIceberg to my Basin Catalog?”: The agent will provide the necessary configuration steps, including retrieving the Catalog URI and Warehouse name, and setting up the required credentials.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/cloudflare/basin/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip basin.zip -d .agents/skills
```

Documentation by Cloudflare

Cloudflare Basin

Basin ingests and transforms events, manages Apache Iceberg tables in R2, and queries them with distributed SQL. Start with the Basin overview and retrieve the relevant current docs before implementing changes, especially for limits, pricing, permissions, and CLI syntax. While PR #33850 remains open, use the proposed pages in that PR if the new URLs have not been published.

Rebrand

Cloudflare Data Platform is now Basin. Cloudflare Pipelines, R2 Data Catalog, and R2 SQL are now Basin Pipelines, Basin Catalog, and Basin SQL. Existing resources and configurations continue to work. The prior Wrangler command families also continue to work: wrangler pipelines, wrangler r2 bucket catalog, and wrangler r2 sql. Use the new Basin commands and documentation URLs in new guidance. Legacy API identifiers and metrics names may still use the old terms; check the current docs for deprecation details. The migration is documented in cloudflare-docs PR #33850.

Choose the workflow

Need	Product	Reference	Current docs
Receive events, transform rows, and deliver to R2	Basin Pipelines	Pipelines guide	Basin Pipelines
Manage Iceberg metadata, table maintenance, and engine access	Basin Catalog	Catalog guide	Basin Catalog
Query Iceberg tables with analytical SQL	Basin SQL	SQL guide	Basin SQL

Typical flow: Basin Pipelines → Basin Catalog tables in R2 → Basin SQL or a compatible external engine. Begin with the Basin getting started guide for an end-to-end setup.

The proposed Wrangler command families are wrangler basin pipelines, wrangler basin catalog, and wrangler basin sql. Basin SQL uses WRANGLER_BASIN_SQL_AUTH_TOKEN; its REST query path is /basin-sql/query/{BUCKET}. Check the installed Wrangler version and current reference pages before running commands because the migration is ongoing.

Skill feedback

If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.

Files

ATTRIBUTION.mdAdded by AutoGineer846 B
LICENSELicence file added by AutoGineer11.1 KiB
SKILL.md2.9 KiB
references/catalog/README.md1.2 KiB
references/catalog/api.md3.3 KiB
references/catalog/configuration.md2.1 KiB
references/catalog/gotchas.md2.2 KiB
references/catalog/patterns.md1.7 KiB
references/pipelines/README.md4.5 KiB
references/pipelines/api.md5.0 KiB
references/pipelines/configuration.md6.1 KiB
references/pipelines/gotchas.md3.0 KiB
references/pipelines/patterns.md4.6 KiB
references/skill-feedback.md2.7 KiB
references/sql/README.md3.4 KiB
references/sql/api.md4.8 KiB
references/sql/configuration.md1.7 KiB
references/sql/gotchas.md2.0 KiB
references/sql/patterns.md4.3 KiB

references/sql/README.md

Basin SQL

Serverless, distributed, read-only query engine (Apache DataFusion) for Apache Iceberg tables in Basin Catalog.

Documentation

For full function lists, data types, and pricing, retrieve the live docs — use the Cloudflare MCP docs tool if available, otherwise webfetch.

Topic	URL
Overview / get started	`https://developers.cloudflare.com/basin-sql/get-started/index.md`
Query data	`https://developers.cloudflare.com/basin-sql/query-data/index.md`
SQL reference	`https://developers.cloudflare.com/basin-sql/sql-reference/index.md`
Aggregate functions	`https://developers.cloudflare.com/basin-sql/sql-reference/aggregate-functions/index.md`
Scalar functions	`https://developers.cloudflare.com/basin-sql/sql-reference/scalar-functions/index.md`
Complex types	`https://developers.cloudflare.com/basin-sql/sql-reference/complex-types/index.md`
Limitations & best practices	`https://developers.cloudflare.com/basin-sql/reference/limitations-best-practices/index.md`
Wrangler commands	`https://developers.cloudflare.com/basin-sql/reference/wrangler-commands/index.md`
Pricing	`https://developers.cloudflare.com/basin-sql/platform/pricing/index.md`

Connection Values

Value	Format
REST endpoint	`https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/basin-sql/query/{BUCKET}`
Wrangler	`npx wrangler basin sql query "{WAREHOUSE}" "<SQL>"` with `WRANGLER_BASIN_SQL_AUTH_TOKEN` set
Warehouse	`{ACCOUNT_ID}_{BUCKET}`

The REST endpoint is api.sql.cloudflarestorage.com — not the account API host. The legacy /r2-sql/query/ path may still work, but use /basin-sql/query/ for new integrations.

Quick Start

npx wrangler basin catalog enable my-bucket           # 1. enable catalog
export WRANGLER_BASIN_SQL_AUTH_TOKEN=<r2-token>              # 2. auth (Admin R&W + Basin SQL Read)
npx wrangler basin sql query "$ACCOUNT_ID"_my-bucket \
  "SELECT * FROM default.my_table LIMIT 10"                # 3. query

SQL Surface

Basin SQL is read-only and supports a broad analytical SQL surface (SELECT, JOINs, subqueries, CTEs, set operations, window functions, and aggregate/scalar/JSON functions over complex types). For the authoritative, current list of supported syntax, functions, and limitations, see the SQL reference and limitations docs linked above. api.md has query templates.

When to Use

Use for: SQL analytics over Iceberg (logs, BI, fraud, ad-hoc), multi-cloud queries without egress, dashboards (query from a Worker via HTTP).

Don't use for: writes (use PySpark/PyIceberg) or real-time OLTP (<100 ms).

No Workers Binding

There is no env.R2_SQL binding. Query from a Worker via fetch() to the REST endpoint with the token as a secret (see patterns.md).

Reading Order

configuration.md — enable catalog, tokens, env setup
api.md — SQL syntax templates, JOIN/window examples, response format, data types
patterns.md — CLI/REST/Worker queries, use cases, pagination, performance
gotchas.md — what works vs. not, performance, troubleshooting

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Anndata
K-Dense· Community
A Python framework for managing annotated data matrices in single-cell genomics and general research workflows.
Data and AIClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskGitHub stars of the source repository56.4k
Liteparse
K-Dense· Community
Local document and PDF parsing with spatial text extraction and bounding box support.
Data and AIClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0Low riskHas scriptsGitHub stars of the source repository56.4k
Usfiscaldata
K-Dense· Community
Access U.S. Treasury federal financial data via the Fiscal Data REST API.
Data and AIClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskGitHub stars of the source repository56.4k
Geopandas
K-Dense· Community
Guidance and local audit tools for Python workflows using GeoPandas 1.2.0 for spatial data analysis.
Data and AIClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository56.4k
Markitdown
K-Dense· Community
A lightweight utility for converting diverse document formats into structured Markdown for analysis, search, and LLM ingestion.
Data and AIClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository56.4k
Zarr Python
K-Dense· Community
A guide for storing and querying chunked N-D scientific arrays using Zarr-Python 3.
Data and AIClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskGitHub stars of the source repository56.4k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download basin.zip

From the author