memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/graphql-api/gotchas.md

@@ -0,0 +1,111 @@
+# GraphQL Analytics API Gotchas & Troubleshooting
+
+## Rate Limits
+
+| Limit                    | Value                                                     |
+| ------------------------ | --------------------------------------------------------- |
+| GraphQL queries per user | **Default 300 per 5 minutes** (max 320, at least 1/sec)   |
+| General API rate limit   | 1200 requests per 5 minutes (shared across all API calls) |
+| Zone scope per query     | Up to **10 zones**                                        |
+| Account scope per query  | Exactly **1 account**                                     |
+
+The GraphQL rate limit is separate from the general API limit. Exceeding either results in `HTTP 429` and blocks all API calls for 5 minutes. Enterprise customers can contact support to raise limits.
+
+### "429 Too Many Requests"
+
+**Cause:** Exceeded rate limit.
+
+**Solution:** Batch multiple datasets into single queries, cache results, increase intervals between queries. Use `{ viewer { budget } }` to monitor remaining budget.
+
+## Sampling & Data Accuracy
+
+### Adaptive Bit Rate (ABR) Sampling
+
+Datasets with `Adaptive` in the name use adaptive sampling:
+
+- Results are **statistically representative**, not exact
+- Same query may return **slightly different numbers** each run
+- Higher traffic = higher sampling rate = more accurate
+- `sampleInterval` dimension shows the ratio (1 = no sampling, 10 = ~1-in-10 sampled)
+
+For high-confidence numbers, use `confidence(level: 0.95)` to get estimate bounds. For exact counts, use rollup nodes (`httpRequests1hGroups`, `httpRequests1dGroups`) which are pre-aggregated without sampling.
+
+### Rollup vs. Adaptive
+
+| Feature     | Rollup (`*1hGroups`, `*1dGroups`) | Adaptive (`*AdaptiveGroups`) |
+| ----------- | --------------------------------- | ---------------------------- |
+| Sampling    | No (pre-aggregated)               | Yes (ABR)                    |
+| Flexibility | Fixed time buckets                | Any granularity              |
+| Dimensions  | Fewer                             | Many more                    |
+| Accuracy    | Exact                             | Statistical estimate         |
+
+## Common Errors
+
+### "Access denied" / "authentication error"
+
+**Cause:** Token lacks required permission or wrong scope.
+
+**Solution:** Account-scoped queries need **Account Analytics: Read**. Zone-scoped queries need **Zone Analytics: Read**. Verify: `curl -s https://api.cloudflare.com/client/v4/user/tokens/verify -H "Authorization: Bearer $TOKEN"`
+
+### "field not found" / "Cannot query field"
+
+**Cause:** Wrong dataset name, nonexistent field, or wrong scope (zone vs. account).
+
+**Solution:** Names are case-sensitive camelCase (`httpRequestsAdaptiveGroups`). Zone datasets go under `zones(...)`, account datasets under `accounts(...)`. Use introspection to verify.
+
+### "filter is required" / empty results
+
+**Cause:** Missing required time range filter or incorrect zone/account tag.
+
+**Solution:** Always include `datetime_gt` / `datetime_lt` (or `_geq` / `_leq`).
+
+### "limit is required" / "limit exceeds maximum"
+
+**Cause:** Missing `limit` or exceeding node's max page size.
+
+**Solution:** Always specify `limit`. Max varies by dataset (typically 10,000 for groups, 100 for raw events). Check via settings query.
+
+### "query is too complex" / "query exceeds budget"
+
+**Cause:** Too many fields, datasets, or too broad a time range.
+
+**Solution:** Reduce time range, request fewer dimensions/metrics, break into smaller queries. Monitor `cost` and `budget` in responses.
+
+### 200 Response with Errors
+
+GraphQL returns HTTP 200 even on failures. **Always check `response.errors`:**
+
+```json
+{ "data": null, "errors": [{ "message": "filter is required for httpRequestsAdaptiveGroups" }] }
+```
+
+## Plan-Based Availability
+
+Not all datasets are available on all plans. Higher plans get more datasets, longer retention (`notOlderThan`), wider time ranges (`maxDuration`), more fields, and larger page sizes.
+
+### "node is not available" / "node is disabled"
+
+**Cause:** Dataset not on your plan, or product not enabled.
+
+**Solution:** Check `settings { <nodeName> { enabled } }`. Some datasets require specific subscriptions (e.g., Network Analytics requires Magic Transit/Spectrum).
+
+## DateTime & Timezone Handling
+
+- All times are **UTC only** (ISO 8601: `"2025-01-15T10:30:00Z"`)
+- `Date` type: `"2025-01-15"` (used in `date_geq`/`date_leq` for storage datasets)
+- `Time` type: `"2025-01-15T10:30:00Z"` (used in `datetime_gt`/`datetime_lt`)
+- Filters are start-inclusive: events that start within the window are included
+
+## Performance Tips
+
+- **Narrow time ranges** are faster and cheaper
+- **Select only needed dimensions** — each additional dimension increases cost
+- **Use rollup nodes** (`*1dGroups`) for simple daily totals without dimension breakdowns
+- **Batch datasets** into one query instead of separate HTTP requests
+
+## See Also
+
+- [README.md](README.md) - Overview, decision tree, dataset index
+- [api.md](api.md) - Query structure, aggregation fields, filtering operators
+- [configuration.md](configuration.md) - Authentication, client setup, introspection queries
+- [patterns.md](patterns.md) - Common query patterns (time-series, top-N, per-product)

package/skills/cloudflare/references/graphql-api/patterns.md

@@ -0,0 +1,276 @@
+# GraphQL Analytics API Patterns & Best Practices
+
+## Time-Series Queries
+
+Use time dimension granularity matching your range (see Best Practices below).
+
+```graphql
+query TrafficTimeSeries($zoneTag: string!, $start: Time!, $end: Time!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpRequestsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 1000
+        orderBy: [datetimeFiveMinutes_ASC] # or datetimeHour_ASC for longer ranges
+      ) {
+        count
+        dimensions {
+          datetimeFiveMinutes
+        }
+        sum {
+          edgeResponseBytes
+        }
+        ratio {
+          status4xx
+          status5xx
+        }
+      }
+    }
+  }
+}
+```
+
+## Top-N Queries
+
+### Top Countries by Request Count
+
+```graphql
+query TopCountries($zoneTag: string!, $start: Time!, $end: Time!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpRequestsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 10
+        orderBy: [count_DESC]
+      ) {
+        count
+        dimensions {
+          clientCountryName
+        }
+      }
+    }
+  }
+}
+```
+
+Use `orderBy: [sum_edgeResponseBytes_DESC]` for top paths by bandwidth. Add `edgeResponseStatus_geq: 400` to the filter for top error status codes.
+
+## Workers Analytics
+
+```graphql
+query WorkersOverview($accountTag: string!, $start: Time!, $end: Time!) {
+  viewer {
+    accounts(filter: { accountTag: $accountTag }) {
+      workersInvocationsAdaptive(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 100
+        orderBy: [sum_requests_DESC]
+      ) {
+        sum {
+          requests
+          errors
+          subrequests
+          wallTime
+        }
+        quantiles {
+          cpuTimeP50
+          cpuTimeP99
+          wallTimeP50
+          wallTimeP99
+        }
+        dimensions {
+          scriptName
+        }
+      }
+    }
+  }
+}
+```
+
+Filter by `scriptName` for a specific Worker. Add `datetimeFiveMinutes` dimension + `orderBy: [datetimeFiveMinutes_ASC]` for error rate over time.
+
+## Firewall / Security
+
+```graphql
+query RecentFirewallEvents($zoneTag: string!, $start: Time!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      firewallEventsAdaptive(filter: { datetime_gt: $start }, limit: 50, orderBy: [datetime_DESC]) {
+        action
+        source
+        clientIP
+        clientCountryName
+        userAgent
+        clientRequestHTTPHost
+        clientRequestPath
+        ruleId
+        datetime
+      }
+    }
+  }
+}
+```
+
+For aggregated firewall stats, use `firewallEventsAdaptiveGroups` with `action: "block"` filter and group by `ruleId`, `source`, `datetimeHour`.
+
+## DNS Analytics
+
+```graphql
+query DNSQueryVolume($zoneTag: string!, $start: Time!, $end: Time!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      dnsAnalyticsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 500
+        orderBy: [datetimeFiveMinutes_ASC]
+      ) {
+        count
+        dimensions {
+          datetimeFiveMinutes
+        }
+      }
+    }
+  }
+}
+```
+
+## Storage Analytics (Account-Scoped)
+
+R2, KV, and D1 use `date` (Date type) filters instead of `datetime` (Time type).
+
+```graphql
+# R2 operations
+r2OperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
+  dimensions { date bucketName actionType }
+  sum { requests }
+}
+
+# KV operations
+kvOperationsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
+  dimensions { date actionType }
+  sum { requests }
+}
+
+# D1 analytics
+d1AnalyticsAdaptiveGroups(filter: { date_geq: $start, date_leq: $end }, limit: 100, orderBy: [date_DESC]) {
+  dimensions { date databaseId }
+  sum { readQueries writeQueries rowsRead rowsWritten }
+}
+```
+
+## Cache Analytics
+
+```graphql
+query CacheStatusBreakdown($zoneTag: string!, $start: Time!, $end: Time!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpRequestsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 20
+        orderBy: [count_DESC]
+      ) {
+        count
+        dimensions {
+          cacheStatus
+        }
+        sum {
+          edgeResponseBytes
+        }
+      }
+    }
+  }
+}
+```
+
+For cache hit ratio over time, use aliases to query the same dataset twice — once with `cacheStatus: "hit"` filter and once without — then compute the ratio client-side.
+
+## Multi-Dataset Queries
+
+A single request can query multiple datasets, avoiding extra HTTP round-trips:
+
+```graphql
+query DashboardOverview($zoneTag: string!, $start: Time!, $end: Time!) {
+  viewer {
+    zones(filter: { zoneTag: $zoneTag }) {
+      httpTraffic: httpRequestsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 1
+      ) {
+        count
+        sum {
+          edgeResponseBytes
+        }
+        ratio {
+          status4xx
+          status5xx
+        }
+      }
+      firewallEvents: firewallEventsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 5
+        orderBy: [count_DESC]
+      ) {
+        count
+        dimensions {
+          action
+          source
+        }
+      }
+      dnsQueries: dnsAnalyticsAdaptiveGroups(
+        filter: { datetime_gt: $start, datetime_lt: $end }
+        limit: 1
+      ) {
+        count
+      }
+    }
+  }
+}
+```
+
+## AI & Gateway Analytics
+
+```graphql
+# Workers AI inference
+aiInferenceAdaptiveGroups(
+  filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
+) {
+  count
+  sum { totalInputTokens totalOutputTokens totalRequestBytesIn }
+  dimensions { modelId datetimeHour }
+}
+
+# AI Gateway requests
+aiGatewayRequestsAdaptiveGroups(
+  filter: { datetime_gt: $start, datetime_lt: $end }, limit: 100, orderBy: [datetimeHour_DESC]
+) {
+  count
+  dimensions { gateway provider model datetimeHour }
+  sum { cachedTokensIn cachedTokensOut uncachedTokensIn uncachedTokensOut }
+}
+```
+
+Both are account-scoped — nest under `accounts(filter: { accountTag: $accountTag })`.
+
+## Best Practices
+
+**Always include time filters.** Queries without time filters scan all data and are slow/expensive.
+
+**Match time granularity to range:**
+
+| Time Range | Recommended Dimension                             |
+| ---------- | ------------------------------------------------- |
+| < 6 hours  | `datetimeMinute` or `datetimeFiveMinutes`         |
+| 6-48 hours | `datetimeFiveMinutes` or `datetimeFifteenMinutes` |
+| 2-14 days  | `datetimeHour`                                    |
+| 14+ days   | `date`                                            |
+
+**Use aliases** for querying the same dataset with different filters in one request.
+
+**Request only needed fields.** Extra dimensions and metrics increase query cost.
+
+## See Also
+
+- [README.md](README.md) - Overview, decision tree, dataset index
+- [api.md](api.md) - Query structure, aggregation fields, filtering operators
+- [configuration.md](configuration.md) - Authentication, client setup, introspection queries
+- [gotchas.md](gotchas.md) - Rate limits, sampling, troubleshooting

package/skills/cloudflare/references/hyperdrive/README.md

@@ -0,0 +1,84 @@
+# Hyperdrive
+
+Accelerates database queries from Workers via connection pooling, edge setup, query caching.
+
+## Key Features
+
+- **Connection Pooling**: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)
+- **Edge Setup**: Connection negotiation at edge, pooling near origin
+- **Query Caching**: Auto-cache non-mutating queries (default 60s TTL)
+- **Support**: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)
+
+## Architecture
+
+```
+Worker → Edge (setup) → Pool (near DB) → Origin
+         ↓ cached reads
+         Cache
+```
+
+## Quick Start
+
+```bash
+# Create config
+npx wrangler hyperdrive create my-db \
+  --connection-string="postgres://user:pass@host:5432/db"
+
+# wrangler.jsonc
+{
+  "compatibility_flags": ["nodejs_compat"],
+  "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
+}
+```
+
+```typescript
+import { Client } from 'pg'
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const client = new Client({
+      connectionString: env.HYPERDRIVE.connectionString,
+    })
+    await client.connect()
+    const result = await client.query('SELECT * FROM users WHERE id = $1', [123])
+    await client.end()
+    return Response.json(result.rows)
+  },
+}
+```
+
+## When to Use
+
+✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads
+❌ Write-heavy, real-time data (<1s), single-region apps close to DB
+
+**💡 Pair with Smart Placement** for Workers making multiple queries - executes near DB to minimize latency.
+
+## Driver Choice
+
+| Driver               | Use When                                         | Notes                                       |
+| -------------------- | ------------------------------------------------ | ------------------------------------------- |
+| **pg** (recommended) | General use, TypeScript, ecosystem compatibility | Stable, widely used, works with most ORMs   |
+| **postgres.js**      | Advanced features, template literals, streaming  | Lighter than pg, `prepare: true` is default |
+| **mysql2**           | MySQL/MariaDB/PlanetScale                        | MySQL only, less mature support             |
+
+## Reading Order
+
+| New to Hyperdrive                         | Implementing                              | Troubleshooting                 |
+| ----------------------------------------- | ----------------------------------------- | ------------------------------- |
+| 1. README (this)                          | 1. [configuration.md](./configuration.md) | 1. [gotchas.md](./gotchas.md)   |
+| 2. [configuration.md](./configuration.md) | 2. [api.md](./api.md)                     | 2. [patterns.md](./patterns.md) |
+| 3. [api.md](./api.md)                     | 3. [patterns.md](./patterns.md)           | 3. [api.md](./api.md)           |
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Setup, wrangler config, Smart Placement
+- [api.md](./api.md) - Binding APIs, query patterns, driver usage
+- [patterns.md](./patterns.md) - Use cases, ORMs, multi-query optimization
+- [gotchas.md](./gotchas.md) - Limits, troubleshooting, connection management
+
+## See Also
+
+- [smart-placement](../smart-placement/) - Optimize multi-query Workers near databases
+- [d1](../d1/) - Serverless SQLite alternative for edge-native apps
+- [workers](../workers/) - Worker runtime with database bindings

package/skills/cloudflare/references/hyperdrive/api.md

@@ -0,0 +1,149 @@
+# API Reference
+
+See [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.
+
+## Binding Interface
+
+```typescript
+interface Hyperdrive {
+  connectionString: string // PostgreSQL
+  // MySQL properties:
+  host: string
+  port: number
+  user: string
+  password: string
+  database: string
+}
+
+interface Env {
+  HYPERDRIVE: Hyperdrive
+}
+```
+
+**Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)
+
+## PostgreSQL (node-postgres) - RECOMMENDED
+
+```typescript
+import { Client } from 'pg' // pg@^8.17.2
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString })
+    try {
+      await client.connect()
+      const result = await client.query('SELECT * FROM users WHERE id = $1', [123])
+      return Response.json(result.rows)
+    } finally {
+      await client.end()
+    }
+  },
+}
+```
+
+**⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.
+
+## PostgreSQL (postgres.js)
+
+```typescript
+import postgres from 'postgres' // postgres@^3.4.8
+
+const sql = postgres(env.HYPERDRIVE.connectionString, {
+  max: 5, // Limit per Worker (Workers max: 6)
+  prepare: true, // Enabled by default, required for caching
+  fetch_types: false, // Reduce latency if not using arrays
+})
+
+const users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`
+```
+
+**⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.
+
+## MySQL (mysql2)
+
+```typescript
+import { createConnection } from 'mysql2/promise' // mysql2@^3.16.2
+
+const conn = await createConnection({
+  host: env.HYPERDRIVE.host,
+  user: env.HYPERDRIVE.user,
+  password: env.HYPERDRIVE.password,
+  database: env.HYPERDRIVE.database,
+  port: env.HYPERDRIVE.port,
+  disableEval: true, // ⚠️ REQUIRED for Workers
+})
+
+const [results] = await conn.query('SELECT * FROM users WHERE active = ? LIMIT ?', [true, 10])
+ctx.waitUntil(conn.end())
+```
+
+**⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.
+
+## Query Caching
+
+**Cacheable:**
+
+```sql
+SELECT * FROM posts WHERE published = true;
+SELECT COUNT(*) FROM users;
+```
+
+**NOT cacheable:**
+
+```sql
+-- Writes
+INSERT/UPDATE/DELETE
+
+-- Volatile functions
+SELECT NOW();
+SELECT random();
+SELECT LASTVAL();  -- PostgreSQL
+SELECT UUID();     -- MySQL
+```
+
+**Cache config:**
+
+- Default: `max_age=60s`, `swr=15s`
+- Max `max_age`: 3600s
+- Disable: `--caching-disabled=true`
+
+**Multiple configs pattern:**
+
+```typescript
+// Reads: cached
+const sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString)
+const posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`
+
+// Writes/time-sensitive: no cache
+const sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString)
+const orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`
+```
+
+## ORMs
+
+**Drizzle:**
+
+```typescript
+import { drizzle } from 'drizzle-orm/postgres-js' // drizzle-orm@^0.45.1
+import postgres from 'postgres'
+
+const client = postgres(env.HYPERDRIVE.connectionString, { max: 5, prepare: true })
+const db = drizzle(client)
+const users = await db.select().from(users).where(eq(users.active, true)).limit(10)
+```
+
+**Kysely:**
+
+```typescript
+import { Kysely, PostgresDialect } from 'kysely' // kysely@^0.27+
+import postgres from 'postgres'
+
+const db = new Kysely({
+  dialect: new PostgresDialect({
+    postgres: postgres(env.HYPERDRIVE.connectionString, { max: 5, prepare: true }),
+  }),
+})
+const users = await db.selectFrom('users').selectAll().where('active', '=', true).execute()
+```
+
+See [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.