fcakyon/claude-codex-settings / plugins/cloudflare-skills/skills/basin
basin
VerifiedBuild 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
| references/catalog/README.md | markdown | 1.2 KB |
| references/catalog/api.md | markdown | 3.3 KB |
| references/catalog/configuration.md | markdown | 2.1 KB |
| references/catalog/gotchas.md | markdown | 2.2 KB |
| references/catalog/patterns.md | markdown | 1.7 KB |
| references/pipelines/README.md | markdown | 4.5 KB |
| references/pipelines/api.md | markdown | 5.0 KB |
| references/pipelines/configuration.md | markdown | 6.1 KB |
| references/pipelines/gotchas.md | markdown | 3.0 KB |
| references/pipelines/patterns.md | markdown | 4.6 KB |
| references/skill-feedback.md | markdown | 2.7 KB |
| references/sql/README.md | markdown | 3.4 KB |
| references/sql/api.md | markdown | 4.8 KB |
| references/sql/configuration.md | markdown | 1.7 KB |
| references/sql/gotchas.md | markdown | 2.0 KB |
| references/sql/patterns.md | markdown | 4.3 KB |
references/pipelines/patterns.md
View on GitHub# Basin Pipelines Patterns
Code-first patterns. For observability dataset/field schemas and Logpush dataset lists, pull `https://developers.cloudflare.com/basin-pipelines/observability/metrics/index.md` and `https://developers.cloudflare.com/basin-pipelines/streams/logpush/index.md`.
## Fire-and-Forget Producer
```typescript
export default {
async fetch(req, env, ctx) {
const event = { event_id: crypto.randomUUID(), event_type: "page_view", timestamp: new Date().toISOString() };
ctx.waitUntil(env.MY_STREAM.send([event])); // don't block the response
return new Response("OK");
}
};
```
## Client-Side Validation with Zod
Structured streams drop invalid events silently during processing. Validate before sending for immediate feedback.
```typescript
import { z } from "zod";
const EventSchema = z.object({
event_id: z.string(),
category: z.enum(["purchase", "view"]),
amount: z.number().positive().optional(),
});
const validated = EventSchema.parse(rawEvent); // throws synchronously
await env.MY_STREAM.send([validated]);
```
## Scheduled Collector Worker
```jsonc
// wrangler.jsonc
{
"name": "collector",
"pipelines": [{ "stream": "<STREAM_ID>", "binding": "EVENT_STREAM" }],
"triggers": { "crons": ["*/5 * * * *"] }
}
```
```typescript
export default {
async scheduled(event, env, ctx) {
const items = await (await fetch("https://api.example.com/data")).json();
const events = items.map(i => ({
event_id: crypto.randomUUID(),
timestamp: new Date().toISOString(),
category: i.type, amount: i.value,
}));
await env.EVENT_STREAM.send(events);
},
};
```
## Logpush → Basin Pipelines
Basin Pipelines is a native Logpush destination — ingest Cloudflare logs, transform with SQL, store as Iceberg/Parquet. For the current supported dataset list and field names, pull the Logpush doc above.
```sql
INSERT INTO http_logs_sink
SELECT
ClientIP,
EdgeResponseStatus,
to_timestamp_micros(EdgeStartTimestamp) AS event_time,
upper(ClientRequestMethod) AS method,
sha256(ClientIP) AS hashed_ip -- redact PII at ingest
FROM http_logs_stream
WHERE EdgeResponseStatus >= 400;
```
Configure via Dashboard (**Logpush → Create a job → Basin Pipelines** destination) or API.
## Basin Pipelines + Queues Fan-out
```typescript
await Promise.all([
env.ANALYTICS_STREAM.send([event]), // long-term storage + SQL
env.PROCESS_QUEUE.send(event), // immediate processing + retries
]);
```
Use Basin Pipelines for long-term storage + SQL; Queues for immediate processing/retries/DLQ; both for fan-out.
## Observability (GraphQL Analytics)
Same R2 API token works. Endpoint: `https://api.cloudflare.com/client/v4/graphql`. Datasets cover ingestion, processing (incl. `decodeErrors`), delivery, sink writes (`filesWritten`), and user/validation errors — see the metrics doc for the full dataset/field catalog.
```bash
curl -X POST "https://api.cloudflare.com/client/v4/graphql" \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"query": "query { viewer { accounts(filter: {accountTag: \"'$ACCOUNT_ID'\"}) { pipelinesIngestionAdaptiveGroups(filter: {pipelineId: \"PIPELINE-UUID-WITH-DASHES\", datetime_geq: \"2026-03-01T00:00:00Z\"}, limit: 10) { sum { ingestedRecords ingestedBytes } dimensions { datetimeHour } } } } }"}'
```
> **Sink/pipeline IDs need dashes for GraphQL** but wrangler may show them without: `b909fe6e544844abbd63f6dcbc81d602` → `b909fe6e-5448-44ab-bd63-f6dcbc81d602`. Metrics take 5–10 min to populate.
### Detecting Silent Data Loss
If a sink's bucket is deleted or its token expires, events are accepted but lost. Tell-tale: `recordsWritten > 0` but `filesWritten = 0`. Always verify data lands in R2 within the roll interval and Basin SQL returns expected counts.
## Schema Evolution (Immutable Basin Pipelines)
Basin Pipelines can't change. Version + dual-write:
```bash
npx wrangler basin pipelines streams create events_v2 --schema-file v2.json
```
```typescript
await Promise.all([env.EVENTS_V1.send([event]), env.EVENTS_V2.send([event])]);
// query across versions with UNION ALL in Basin SQL
```
## End-to-End: Streaming Analytics Dashboard
```
External APIs → Collector Worker (cron) → Pipeline → R2 (Iceberg) → Dashboard Worker → Basin SQL
```
1. Create bucket + enable catalog ([Basin Catalog](../catalog/configuration.md))
2. Create stream + sink + pipeline (here)
3. Collector Worker with cron + stream binding (above)
4. Dashboard Worker querying Basin SQL ([sql/patterns.md](../sql/patterns.md))
5. Enable automatic compaction
## See Also
- [configuration.md](configuration.md) · [api.md](api.md) · [gotchas.md](gotchas.md) · [Basin SQL](../sql/)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |