AutoGineer
Generated banner for Basin
Generated logo for Basin

Basin

CloudflareOfficialPublished by Cloudflare

  • Skill
  • Tool integration
  • Data and AI
  • Apache-2.0
  • No issues found
Download ZIP

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

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/cloudflare/basin/download

  2. 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

NeedProductReferenceCurrent docs
Receive events, transform rows, and deliver to R2Basin PipelinesPipelines guideBasin Pipelines
Manage Iceberg metadata, table maintenance, and engine accessBasin CatalogCatalog guideBasin Catalog
Query Iceberg tables with analytical SQLBasin SQLSQL guideBasin 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

references/sql/gotchas.md

Basin SQL Gotchas

Operational pitfalls. For the authoritative list of supported features, unsupported features, and recommended workarounds, pull https://developers.cloudflare.com/basin-sql/reference/limitations-best-practices/index.md and https://developers.cloudflare.com/basin-sql/troubleshooting/index.md.

Access

  • No Workers binding. There is no env.R2_SQL. Query the REST endpoint via fetch() from a Worker (patterns.md), or use D1 / an external DB for OLTP.

  • Wrangler needs WRANGLER_BASIN_SQL_AUTH_TOKEN — it does not reuse the wrangler login OAuth session.

  • R2 Storage Admin Read & Write is currently required even for read-only queries. Verify this in the live authentication docs.

Type Safety

-- ❌ wrong                          -- ✅ right
WHERE status = '200'                 WHERE status = 200
WHERE ts > '2026-01-01'              WHERE ts > '2026-01-01T00:00:00Z'   -- need time + tz
WHERE method = GET                   WHERE method = 'GET'

No implicit conversions. Timestamps must be RFC3339 with timezone; dates ISO 8601.

Performance

  • File count dominates latency — enable automatic compaction.

  • Partition-filter + narrow time windows + always LIMIT.

  • Multi-way JOINs on large tables can exceed resource limits — filter heavily, join through dimension tables.

  • Per-query metrics (files_scanned, bytes_scanned, cache_hits) are the primary observability signal; bytes_scanned ≈ billable data. For LIMIT bounds, pagination, and other guidance, see the limitations-best-practices doc.

Debug Checklist

  1. wrangler basin catalog enable <bucket> — catalog on?

  2. echo $WRANGLER_BASIN_SQL_AUTH_TOKEN — token set?

  3. SHOW DATABASES → SHOW TABLES IN ns → DESCRIBE ns.table

  4. SELECT COUNT(*) FROM ns.table — data present?

  5. Add filters incrementally; read metrics to tune.

See Also

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.

Attribution and licence

Published by
Cloudflare
Publisher
Cloudflare (Official)
Source
cloudflare/skills · skills/basin · commit 6eb6c78
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Cloudflare or Cloudflare.

Download ZIP

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