README

This reference is a fast-start with verified code and gotchas. For limits, settings, full SQL syntax, and pricing, retrieve the live docs — use the Cloudflare MCP docs tool if available, otherwise webfetch the URL. Docs are source of truth over this file.

Three Components

Status: The linked docs PR proposes Basin general availability. Verify current availability, limits, and pricing in the live docs before making claims or sizing workloads.

Quick Start

Minimal Worker producer:

Which Sink Type?

Critical Behaviors (read before building)

These are non-obvious and prevent most failures — see gotchas.md for detail.

• Everything is immutable after creation — stream schema, pipeline SQL, sink config. To change, delete and recreate.
• Sinks create their own table — they cannot target an existing Iceberg table.
• __ingest_ts is added automatically (TIMESTAMP, partitioned by day). Don’t define it in your schema.
• Data isn’t queryable immediately — first flush takes 3–7 minutes (warm-up + table creation) even with a short roll interval.
• Schema validation is deferred — invalid events are accepted then silently dropped. Monitor via GraphQL error metrics.
• Binding field renamed pipeline → stream (June 2026); old field still accepted.

Reading Order

1. configuration.md — schema, streams, sinks, pipelines (CLI + REST + Terraform), bindings
2. api.md — send(), HTTP ingest, REST API, pipeline SQL, lifecycle states
3. patterns.md — fire-and-forget, validation, Logpush, observability, end-to-end
4. gotchas.md — silent drops, immutability, REST≠CLI field names

See Also

• Basin Catalog (opens in a new tab) — Iceberg sink destination
• Basin SQL (opens in a new tab) — query the ingested data
• r2 (opens in a new tab) · queues (opens in a new tab) · workers (opens in a new tab)