@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-known-pitfalls/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Too many findings | Legacy codebase | Prioritize security first |
+| Pattern not detected | Complex code | Manual review |
+| False positive | Similar code | Whitelist exceptions |
+| Fix breaks tests | Behavior change | Update tests |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-known-pitfalls/references/examples.md

@@ -0,0 +1,12 @@
+## Examples
+
+### Quick Pitfall Scan
+
+```bash
+# Check for common pitfalls
+grep -r "sk_live_" --include="*.ts" src/        # Key leakage
+grep -r "console.log" --include="*.ts" src/     # Potential PII logging
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-load-scale/SKILL.md

@@ -1,274 +1,403 @@
 ---
 name: supabase-load-scale
-description: |
-  Implement Supabase load testing, auto-scaling, and capacity planning strategies.
-  Use when running performance tests, configuring horizontal scaling,
-  or planning capacity for Supabase integrations.
-  Trigger with phrases like "supabase load test", "supabase scale",
-  "supabase performance test", "supabase capacity", "supabase k6", "supabase benchmark".
-allowed-tools: Read, Write, Edit, Bash(k6:*), Bash(kubectl:*)
+description: 'Scale Supabase projects for production load: read replicas, connection
+  pooling
+
+  tuning via Supavisor, compute size upgrades, CDN caching for Storage,
+
+  Edge Function regional deployment, and database table partitioning.
+
+  Use when preparing for traffic spikes, optimizing connection limits,
+
+  setting up read replicas for analytics queries, or partitioning large tables.
+
+  Trigger with phrases like "supabase scale", "supabase read replica",
+
+  "supabase connection pooling", "supabase compute upgrade",
+
+  "supabase CDN storage", "supabase edge function regions",
+
+  "supabase partitioning", "supavisor", "supabase pool mode".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(supabase:*), Bash(psql:*), Bash(curl:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- scaling
+- performance
+- connection-pooling
+- read-replicas
+- partitioning
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Supabase Load & Scale
 
 ## Overview
-Load testing, scaling strategies, and capacity planning for Supabase integrations.
+
+Supabase scaling operates at six layers: **read replicas** (offload analytics and reporting queries), **connection pooling** (Supavisor pgBouncer replacement with transaction/session modes), **compute upgrades** (vCPU/RAM tiers), **CDN for Storage** (cache public bucket assets at the edge), **Edge Function regions** (deploy functions closer to users), and **table partitioning** (split billion-row tables for query performance). This skill covers each layer with real `createClient` configuration, SQL, and CLI commands.
 
 ## Prerequisites
-- k6 load testing tool installed
-- Kubernetes cluster with HPA configured
-- Prometheus for metrics collection
-- Test environment API keys
-
-## Load Testing with k6
-
-### Basic Load Test
-```javascript
-// supabase-load-test.js
-import http from 'k6/http';
-import { check, sleep } from 'k6';
-
-export const options = {
-  stages: [
-    { duration: '2m', target: 10 },   // Ramp up
-    { duration: '5m', target: 10 },   // Steady state
-    { duration: '2m', target: 50 },   // Ramp to peak
-    { duration: '5m', target: 50 },   // Stress test
-    { duration: '2m', target: 0 },    // Ramp down
-  ],
-  thresholds: {
-    http_req_duration: ['p(95)<200'],
-    http_req_failed: ['rate<0.01'],
-  },
-};
-
-export default function () {
-  const response = http.post(
-    'https://api.supabase.com/v1/resource',
-    JSON.stringify({ test: true }),
-    {
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${__ENV.SUPABASE_API_KEY}`,
-      },
-    }
-  );
 
-  check(response, {
-    'status is 200': (r) => r.status === 200,
-    'latency < 200ms': (r) => r.timings.duration < 200,
-  });
+- Supabase project on a Pro plan or higher (read replicas require Pro+)
+- `@supabase/supabase-js` v2+ installed
+- `supabase` CLI installed and linked to your project
+- Database access via `psql` or Supabase SQL Editor
+- TypeScript project with generated database types
 
-  sleep(1);
-}
+## Step 1 — Read Replicas and Connection Pooling
+
+Read replicas let you route read-heavy queries (dashboards, reports, search) to replica databases while keeping writes on the primary. Supabase uses **Supavisor** (their pgBouncer replacement) for connection pooling with two modes: **transaction** (default, shares connections between requests) and **session** (holds a connection per client session, needed for prepared statements).
+
+### Configure the Read Replica Client
+
+```typescript
+// lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from './database.types'
+
+// Primary client — handles all writes and real-time subscriptions
+export const supabase = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+)
+
+// Read replica client — use for analytics, dashboards, search
+// The read replica URL is available in Dashboard > Settings > Database
+export const supabaseReadOnly = createClient<Database>(
+  process.env.SUPABASE_READ_REPLICA_URL!,  // e.g., https://<project-ref>-ro.supabase.co
+  process.env.SUPABASE_ANON_KEY!,          // same anon key works for replicas
+  {
+    db: { schema: 'public' },
+    // Replicas may have slight lag (typically <100ms)
+    // Do NOT use for reads-after-writes in the same request
+  }
+)
+
+// Server-side admin client with connection pooling via Supavisor
+// Use the pooled connection string (port 6543) instead of direct (port 5432)
+export const supabaseAdmin = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  {
+    auth: { autoRefreshToken: false, persistSession: false },
+    db: { schema: 'public' },
+  }
+)
 ```
 
-### Run Load Test
+### Direct Postgres Connections via Supavisor Pooling
+
 ```bash
-# Install k6
-brew install k6  # macOS
-# or: sudo apt install k6  # Linux
+# Transaction mode (default, port 6543) — best for serverless/short-lived connections
+# Shares connections across clients. Cannot use prepared statements.
+psql "postgresql://postgres.[project-ref]:[password]@aws-0-us-east-1.pooler.supabase.com:6543/postgres"
 
-# Run test
-k6 run --env SUPABASE_API_KEY=${SUPABASE_API_KEY} supabase-load-test.js
+# Session mode (port 5432 via pooler) — needed for prepared statements, LISTEN/NOTIFY
+# One-to-one connection mapping per client.
+psql "postgresql://postgres.[project-ref]:[password]@aws-0-us-east-1.pooler.supabase.com:5432/postgres"
 
-# Run with output to InfluxDB
-k6 run --out influxdb=http://localhost:8086/k6 supabase-load-test.js
+# Direct connection (no pooling) — for migrations and admin tasks only
+psql "postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres"
 ```
 
-## Scaling Patterns
-
-### Horizontal Scaling
-```yaml
-# kubernetes HPA
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: supabase-integration-hpa
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: supabase-integration
-  minReplicas: 2
-  maxReplicas: 20
-  metrics:
-    - type: Resource
-      resource:
-        name: cpu
-        target:
-          type: Utilization
-          averageUtilization: 70
-    - type: Pods
-      pods:
-        metric:
-          name: supabase_queue_depth
-        target:
-          type: AverageValue
-          averageValue: 100
-```
+### Route Queries to the Right Target
 
-### Connection Pooling
 ```typescript
-import { Pool } from 'generic-pool';
-
-const supabasePool = Pool.create({
-  create: async () => {
-    return new SupabaseClient({
-      apiKey: process.env.SUPABASE_API_KEY!,
-    });
-  },
-  destroy: async (client) => {
-    await client.close();
-  },
-  max: 20,
-  min: 5,
-  idleTimeoutMillis: 30000,
-});
-
-async function withSupabaseClient<T>(
-  fn: (client: SupabaseClient) => Promise<T>
-): Promise<T> {
-  const client = await supabasePool.acquire();
-  try {
-    return await fn(client);
-  } finally {
-    supabasePool.release(client);
-  }
+// services/analytics.ts
+import { supabaseReadOnly } from '../lib/supabase'
+
+// Heavy analytics queries go to the read replica
+export async function getDashboardMetrics(orgId: string) {
+  const { data, error } = await supabaseReadOnly
+    .from('events')
+    .select('event_type, count:id.count()')
+    .eq('org_id', orgId)
+    .gte('created_at', new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString())
+
+  if (error) throw new Error(`Dashboard query failed: ${error.message}`)
+  return data
+}
+
+// services/orders.ts
+import { supabase } from '../lib/supabase'
+
+// Writes always go to the primary
+export async function createOrder(order: OrderInsert) {
+  const { data, error } = await supabase
+    .from('orders')
+    .insert(order)
+    .select('id, status, total, created_at')
+    .single()
+
+  if (error) throw new Error(`Order creation failed: ${error.message}`)
+  return data
 }
 ```
 
-## Capacity Planning
+### Monitor Connection Pool Usage
+
+```sql
+-- Check active connections by source (run in SQL Editor)
+SELECT
+  usename,
+  application_name,
+  client_addr,
+  state,
+  count(*) AS connections
+FROM pg_stat_activity
+WHERE datname = 'postgres'
+GROUP BY usename, application_name, client_addr, state
+ORDER BY connections DESC;
+
+-- Check connection limits for your compute tier
+SHOW max_connections;
+-- Micro: 60, Small: 90, Medium: 120, Large: 160, XL: 240, 2XL: 380, 4XL: 480
+```
+
+## Step 2 — Compute Upgrades, CDN for Storage, and Edge Function Regions
+
+### Compute Size Selection Guide
+
+| Tier | vCPU | RAM | Max Connections | Best For |
+|------|------|-----|----------------|----------|
+| Micro (Free) | 2 shared | 1 GB | 60 | Development, prototypes |
+| Small (Pro) | 2 dedicated | 2 GB | 90 | Low-traffic production |
+| Medium | 2 dedicated | 4 GB | 120 | Growing apps, moderate traffic |
+| Large | 4 dedicated | 8 GB | 160 | High-traffic, complex queries |
+| XL | 8 dedicated | 16 GB | 240 | Large datasets, concurrent users |
+| 2XL | 16 dedicated | 32 GB | 380 | Enterprise, heavy analytics |
+| 4XL | 32 dedicated | 64 GB | 480 | Mission-critical, max throughput |
+
+```bash
+# Upgrade compute via CLI (requires Pro plan)
+supabase projects update --experimental --compute-size small  # or medium, large, xl, 2xl, 4xl
+
+# Check current compute size
+supabase projects list
+```
+
+### CDN Caching for Storage Buckets
 
-### Metrics to Monitor
-| Metric | Warning | Critical |
-|--------|---------|----------|
-| CPU Utilization | > 70% | > 85% |
-| Memory Usage | > 75% | > 90% |
-| Request Queue Depth | > 100 | > 500 |
-| Error Rate | > 1% | > 5% |
-| P95 Latency | > 500ms | > 2000ms |
+Public buckets are automatically served through Supabase's CDN. Optimize cache behavior with proper headers and transforms.
 
-### Capacity Calculation
 ```typescript
-interface CapacityEstimate {
-  currentRPS: number;
-  maxRPS: number;
-  headroom: number;
-  scaleRecommendation: string;
+import { createClient } from '@supabase/supabase-js'
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+)
+
+// Upload with cache-control headers for CDN optimization
+async function uploadPublicAsset(
+  bucket: string,
+  path: string,
+  file: File
+) {
+  const { data, error } = await supabase.storage
+    .from(bucket)
+    .upload(path, file, {
+      cacheControl: '31536000',  // 1 year cache for immutable assets
+      upsert: false,             // prevent accidental overwrites
+      contentType: file.type,
+    })
+
+  if (error) throw new Error(`Upload failed: ${error.message}`)
+
+  // Get the CDN-cached public URL
+  const { data: { publicUrl } } = supabase.storage
+    .from(bucket)
+    .getPublicUrl(path, {
+      transform: {
+        width: 800,        // Image transforms are cached at the CDN edge
+        quality: 80,
+        format: 'webp',
+      },
+    })
+
+  return { path: data.path, publicUrl }
 }
 
-function estimateSupabaseCapacity(
-  metrics: SystemMetrics
-): CapacityEstimate {
-  const currentRPS = metrics.requestsPerSecond;
-  const avgLatency = metrics.p50Latency;
-  const cpuUtilization = metrics.cpuPercent;
-
-  // Estimate max RPS based on current performance
-  const maxRPS = currentRPS / (cpuUtilization / 100) * 0.7; // 70% target
-  const headroom = ((maxRPS - currentRPS) / currentRPS) * 100;
-
-  return {
-    currentRPS,
-    maxRPS: Math.floor(maxRPS),
-    headroom: Math.round(headroom),
-    scaleRecommendation: headroom < 30
-      ? 'Scale up soon'
-      : headroom < 50
-      ? 'Monitor closely'
-      : 'Adequate capacity',
-  };
+// Bust cache by uploading to a new path (content-addressed)
+import { createHash } from 'crypto'
+
+async function uploadVersionedAsset(bucket: string, file: Buffer, ext: string) {
+  const hash = createHash('sha256').update(file).digest('hex').slice(0, 12)
+  const path = `assets/${hash}.${ext}`
+
+  const { error } = await supabase.storage
+    .from(bucket)
+    .upload(path, file, {
+      cacheControl: '31536000',
+      upsert: false,
+    })
+
+  if (error && error.message !== 'The resource already exists') {
+    throw new Error(`Versioned upload failed: ${error.message}`)
+  }
+
+  return supabase.storage.from(bucket).getPublicUrl(path).data.publicUrl
 }
 ```
 
-## Benchmark Results Template
-
-```markdown
-## Supabase Performance Benchmark
-**Date:** YYYY-MM-DD
-**Environment:** [staging/production]
-**SDK Version:** X.Y.Z
-
-### Test Configuration
-- Duration: 10 minutes
-- Ramp: 10 → 100 → 10 VUs
-- Target endpoint: /v1/resource
-
-### Results
-| Metric | Value |
-|--------|-------|
-| Total Requests | 50,000 |
-| Success Rate | 99.9% |
-| P50 Latency | 120ms |
-| P95 Latency | 350ms |
-| P99 Latency | 800ms |
-| Max RPS Achieved | 150 |
-
-### Observations
-- [Key finding 1]
-- [Key finding 2]
-
-### Recommendations
-- [Scaling recommendation]
-```
+### Edge Function Regional Deployment
 
-## Instructions
+```bash
+# Deploy to a specific region (closer to your users)
+supabase functions deploy my-function --region us-east-1
+supabase functions deploy my-function --region eu-west-1
+supabase functions deploy my-function --region ap-southeast-1
 
-### Step 1: Create Load Test Script
-Write k6 test script with appropriate thresholds.
+# List available regions
+supabase functions list
 
-### Step 2: Configure Auto-Scaling
-Set up HPA with CPU and custom metrics.
+# Deploy all functions to a region
+supabase functions deploy --region us-east-1
+```
 
-### Step 3: Run Load Test
-Execute test and collect metrics.
+```typescript
+// supabase/functions/geo-router/index.ts
+// Edge Function that runs in the region closest to the user
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+Deno.serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  )
+
+  // Edge Functions automatically run in the nearest region
+  // Use this for latency-sensitive operations
+  const { data, error } = await supabase
+    .from('products')
+    .select('id, name, price')
+    .eq('region', req.headers.get('x-region') ?? 'us')
+    .limit(20)
+
+  if (error) {
+    return new Response(JSON.stringify({ error: error.message }), { status: 500 })
+  }
 
-### Step 4: Analyze and Document
-Record results in benchmark template.
+  return new Response(JSON.stringify(data), {
+    headers: {
+      'Content-Type': 'application/json',
+      'Cache-Control': 'public, max-age=60',  // CDN caches the response
+    },
+  })
+})
+```
+
+## Step 3 — Database Table Partitioning
+
+See [table partitioning patterns](references/table-partitioning.md) for range partitioning by date, automated partition creation via `pg_cron`, SDK query patterns with partition key filters, and partition drop for data retention.
 
 ## Output
-- Load test script created
-- HPA configured
-- Benchmark results documented
-- Capacity recommendations defined
+
+- Read replica client configured for analytics/dashboard queries, primary for writes
+- Connection pooling mode selected (transaction vs session) with correct port
+- Compute tier matched to traffic requirements
+- Storage uploads optimized with CDN cache headers and image transforms
+- Edge Functions deployed to the region closest to users
+- Large tables partitioned by date range with automated partition management
+- Data retention policy via partition drops
 
 ## Error Handling
+
 | Issue | Cause | Solution |
 |-------|-------|----------|
-| k6 timeout | Rate limited | Reduce RPS |
-| HPA not scaling | Wrong metrics | Verify metric name |
-| Connection refused | Pool exhausted | Increase pool size |
-| Inconsistent results | Warm-up needed | Add ramp-up phase |
+| `too many connections for role` | Exceeded Supavisor pool limit | Use transaction mode (port 6543), reduce idle connections, upgrade compute |
+| Read replica returns stale data | Replication lag (typically <100ms) | Do not read-after-write on replica; use primary for consistency-critical reads |
+| `no partition of relation "events" found for row` | Insert date outside any partition range | Create a DEFAULT partition or pre-create future partitions |
+| Storage CDN returns old file | Cached at edge | Use content-addressed paths (`hash.ext`) or set shorter `cacheControl` |
+| Edge Function cold start | First request to a region | Use `keep-alive` cron ping or accept ~200ms cold start |
+| `prepared statement already exists` | Transaction mode doesn't support prepared statements | Switch to session mode (port 5432) or disable prepared statements in your ORM |
 
 ## Examples
 
-### Quick k6 Test
+### Quick Connection Pool Check
+
 ```bash
-k6 run --vus 10 --duration 30s supabase-load-test.js
+# Check how many connections are in use right now
+psql "$DATABASE_URL" -c "SELECT count(*) AS active_connections FROM pg_stat_activity WHERE state = 'active';"
 ```
 
-### Check Current Capacity
-```typescript
-const metrics = await getSystemMetrics();
-const capacity = estimateSupabaseCapacity(metrics);
-console.log('Headroom:', capacity.headroom + '%');
-console.log('Recommendation:', capacity.scaleRecommendation);
+### Switch an Existing Table to Partitioned
+
+```sql
+-- You cannot ALTER an existing table to be partitioned.
+-- Instead: create partitioned table, migrate data, swap names.
+
+-- 1. Create new partitioned table
+CREATE TABLE public.events_partitioned (LIKE public.events INCLUDING ALL)
+  PARTITION BY RANGE (created_at);
+
+-- 2. Create partitions for existing data range
+CREATE TABLE public.events_p_2025_01 PARTITION OF public.events_partitioned
+  FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');
+-- ... more partitions
+
+-- 3. Copy data (do this during low traffic)
+INSERT INTO public.events_partitioned SELECT * FROM public.events;
+
+-- 4. Swap tables in a transaction
+BEGIN;
+  ALTER TABLE public.events RENAME TO events_old;
+  ALTER TABLE public.events_partitioned RENAME TO events;
+COMMIT;
+
+-- 5. Verify, then drop old table
+DROP TABLE public.events_old;
 ```
 
-### Scale HPA Manually
-```bash
-kubectl scale deployment supabase-integration --replicas=5
-kubectl get hpa supabase-integration-hpa
+### Test Read Replica Lag
+
+```typescript
+import { supabase, supabaseReadOnly } from '../lib/supabase'
+
+async function measureReplicaLag() {
+  // Write to primary
+  const { data: written } = await supabase
+    .from('health_checks')
+    .insert({ timestamp: new Date().toISOString() })
+    .select('id, timestamp')
+    .single()
+
+  // Immediately read from replica
+  const start = Date.now()
+  let found = false
+
+  while (!found && Date.now() - start < 5000) {
+    const { data } = await supabaseReadOnly
+      .from('health_checks')
+      .select('id')
+      .eq('id', written!.id)
+      .maybeSingle()
+
+    if (data) {
+      found = true
+      console.log(`Replica lag: ${Date.now() - start}ms`)
+    } else {
+      await new Promise(r => setTimeout(r, 10))
+    }
+  }
+
+  if (!found) console.warn('Replica lag exceeds 5 seconds')
+}
 ```
 
 ## Resources
-- [k6 Documentation](https://k6.io/docs/)
-- [Kubernetes HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/)
-- [Supabase Rate Limits](https://supabase.com/docs/rate-limits)
+
+- [Supabase Read Replicas](https://supabase.com/docs/guides/platform/read-replicas)
+- [Supabase Connection Pooling (Supavisor)](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)
+- [Supabase Compute Add-ons](https://supabase.com/docs/guides/platform/compute-add-ons)
+- [Supabase Storage CDN](https://supabase.com/docs/guides/storage/cdn/fundamentals)
+- [Supabase Edge Functions](https://supabase.com/docs/guides/functions)
+- [PostgreSQL Table Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html)
 
 ## Next Steps
-For reliability patterns, see `supabase-reliability-patterns`.
+
+For reliability patterns (circuit breakers, offline queues, graceful degradation), see `supabase-reliability-patterns`.