@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-multi-env-setup/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Wrong environment | Missing NODE_ENV | Set environment variable |
+| Secret not found | Wrong secret path | Verify secret manager config |
+| Config merge fails | Invalid JSON | Validate config files |
+| Production guard triggered | Wrong environment | Check NODE_ENV value |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-multi-env-setup/references/examples.md

@@ -0,0 +1,11 @@
+## Examples
+
+### Quick Environment Check
+
+```typescript
+const env = getSupabaseConfig();
+console.log(`Running in ${env.environment} with ${env.baseUrl}`);
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-observability/SKILL.md

@@ -1,250 +1,372 @@
 ---
 name: supabase-observability
-description: |
-  Set up comprehensive observability for Supabase integrations with metrics, traces, and alerts.
-  Use when implementing monitoring for Supabase operations, setting up dashboards,
-  or configuring alerting for Supabase integration health.
+description: 'Set up monitoring and observability for Supabase projects using Dashboard
+
+  reports, CLI inspect commands, pg_stat_statements, log drains, and alerting.
+
+  Use when implementing monitoring, diagnosing slow queries, forwarding logs,
+
+  or configuring alerts for Supabase project health.
+
   Trigger with phrases like "supabase monitoring", "supabase metrics",
-  "supabase observability", "monitor supabase", "supabase alerts", "supabase tracing".
-allowed-tools: Read, Write, Edit
+
+  "supabase observability", "supabase logs", "supabase alerts",
+
+  "supabase inspect", "supabase log drain".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(npx supabase:*), Bash(supabase:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- monitoring
+- observability
+compatibility: Designed for Claude Code
 ---
-
 # Supabase Observability
 
 ## Overview
-Set up comprehensive observability for Supabase integrations.
+
+Monitor Supabase projects end-to-end: Dashboard reports for API/database/auth metrics, `supabase inspect db` CLI for deep Postgres diagnostics, `pg_stat_statements` for query analytics, log drains for external aggregation, Edge Functions for custom metrics, and alerting on quota thresholds.
 
 ## Prerequisites
-- Prometheus or compatible metrics backend
-- OpenTelemetry SDK installed
-- Grafana or similar dashboarding tool
-- AlertManager configured
 
-## Metrics Collection
+- Supabase CLI installed (`npx supabase --version`)
+- Supabase project linked (`supabase link --project-ref <ref>`)
+- Pro plan or higher for log drain support and extended log retention
+- `@supabase/supabase-js` v2+ installed for application-level monitoring
 
-### Key Metrics
-| Metric | Type | Description |
-|--------|------|-------------|
-| `supabase_requests_total` | Counter | Total API requests |
-| `supabase_request_duration_seconds` | Histogram | Request latency |
-| `supabase_errors_total` | Counter | Error count by type |
-| `supabase_rate_limit_remaining` | Gauge | Rate limit headroom |
+## Instructions
 
-### Prometheus Metrics
+### Step 1: Dashboard Reports and CLI Inspect Commands
 
-```typescript
-import { Registry, Counter, Histogram, Gauge } from 'prom-client';
+Supabase Dashboard provides built-in reports under **Dashboard > Reports**:
 
-const registry = new Registry();
+| Report | What It Shows |
+|--------|---------------|
+| API Requests | Total requests, response times, error rates by endpoint |
+| Database | Active connections, query counts, replication lag |
+| Auth Usage | Signups, logins, provider breakdown, failed attempts |
+| Storage | Bandwidth, object counts, bucket usage |
+| Realtime | Active connections, messages per second, channel counts |
 
-const requestCounter = new Counter({
-  name: 'supabase_requests_total',
-  help: 'Total Supabase API requests',
-  labelNames: ['method', 'status'],
-  registers: [registry],
-});
+For deeper Postgres diagnostics, use the CLI inspect commands:
 
-const requestDuration = new Histogram({
-  name: 'supabase_request_duration_seconds',
-  help: 'Supabase request duration',
-  labelNames: ['method'],
-  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
-  registers: [registry],
-});
+```bash
+# Table sizes — find the largest tables
+npx supabase inspect db table-sizes --linked
 
-const errorCounter = new Counter({
-  name: 'supabase_errors_total',
-  help: 'Supabase errors by type',
-  labelNames: ['error_type'],
-  registers: [registry],
-});
-```
+# Index usage — find unused indexes wasting space
+npx supabase inspect db index-usage --linked
 
-### Instrumented Client
+# Cache hit ratio — should be > 99% (below 95% means upgrade compute)
+npx supabase inspect db cache-hit --linked
 
-```typescript
-async function instrumentedRequest<T>(
-  method: string,
-  operation: () => Promise<T>
-): Promise<T> {
-  const timer = requestDuration.startTimer({ method });
-
-  try {
-    const result = await operation();
-    requestCounter.inc({ method, status: 'success' });
-    return result;
-  } catch (error: any) {
-    requestCounter.inc({ method, status: 'error' });
-    errorCounter.inc({ error_type: error.code || 'unknown' });
-    throw error;
-  } finally {
-    timer();
-  }
-}
-```
+# Sequential scans — tables needing indexes
+npx supabase inspect db seq-scans --linked
 
-## Distributed Tracing
+# Long-running queries — find stuck queries
+npx supabase inspect db long-running-queries --linked
 
-### OpenTelemetry Setup
+# Table index sizes — compare index vs table size
+npx supabase inspect db table-index-sizes --linked
 
-```typescript
-import { trace, SpanStatusCode } from '@opentelemetry/api';
-
-const tracer = trace.getTracer('supabase-client');
-
-async function tracedSupabaseCall<T>(
-  operationName: string,
-  operation: () => Promise<T>
-): Promise<T> {
-  return tracer.startActiveSpan(`supabase.${operationName}`, async (span) => {
-    try {
-      const result = await operation();
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error: any) {
-      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
-      span.recordException(error);
-      throw error;
-    } finally {
-      span.end();
-    }
-  });
-}
+# Bloat — estimate wasted space from dead tuples
+npx supabase inspect db bloat --linked
+
+# Blocking queries — find lock contention
+npx supabase inspect db blocking --linked
+
+# Replication slots — check replication health
+npx supabase inspect db replication-slots --linked
 ```
 
-## Logging Strategy
+### Step 2: Query Analytics with pg_stat_statements and Log Drains
+
+Enable `pg_stat_statements` for detailed query-level metrics:
+
+```sql
+-- Enable the extension (Dashboard > Database > Extensions, or SQL)
+create extension if not exists pg_stat_statements;
+
+-- Top 20 slowest queries by average execution time
+select
+  substring(query, 1, 80) as query_preview,
+  calls,
+  round(mean_exec_time::numeric, 2) as avg_ms,
+  round(max_exec_time::numeric, 2) as max_ms,
+  round(total_exec_time::numeric, 2) as total_ms,
+  rows
+from pg_stat_statements
+where mean_exec_time > 50
+order by mean_exec_time desc
+limit 20;
+
+-- Most-called queries (high call count may indicate N+1 problems)
+select
+  substring(query, 1, 80) as query_preview,
+  calls,
+  round(mean_exec_time::numeric, 2) as avg_ms,
+  rows
+from pg_stat_statements
+order by calls desc
+limit 20;
+
+-- Real-time connection monitoring
+select
+  state,
+  count(*) as connections,
+  max(age(now(), state_change))::text as longest_duration
+from pg_stat_activity
+where datname = current_database()
+group by state
+order by connections desc;
+
+-- Reset stats after optimization (to measure improvement)
+select pg_stat_statements_reset();
+```
 
-### Structured Logging
+**Log drains** forward Supabase logs to external aggregation tools:
+
+```bash
+# Add a Datadog log drain
+npx supabase log-drains add \
+  --name datadog-drain \
+  --type datadog \
+  --datadog-api-key "$DATADOG_API_KEY" \
+  --datadog-region us1 \
+  --linked
+
+# Add a custom HTTP log drain (Logflare, Axiom, etc.)
+npx supabase log-drains add \
+  --name custom-drain \
+  --type webhook \
+  --url "https://api.logflare.app/logs/supabase" \
+  --linked
+
+# List active drains
+npx supabase log-drains list --linked
+
+# Remove a drain
+npx supabase log-drains remove <drain-id> --linked
+```
 
-```typescript
-import pino from 'pino';
+Log drain events include API requests, Auth events, Postgres logs, Storage operations, and Edge Function invocations.
 
-const logger = pino({
-  name: 'supabase',
-  level: process.env.LOG_LEVEL || 'info',
-});
+### Step 3: Custom Metrics, Alerting, and Health Checks
+
+**Custom metrics via Edge Functions** — emit structured events for business-level monitoring:
 
-function logSupabaseOperation(
-  operation: string,
-  data: Record<string, any>,
-  duration: number
-) {
-  logger.info({
-    service: 'supabase',
-    operation,
-    duration_ms: duration,
-    ...data,
+```typescript
+// supabase/functions/collect-metrics/index.ts
+import { createClient } from '@supabase/supabase-js';
+import { serve } from 'https://deno.land/std@0.177.0/http/server.ts';
+
+serve(async () => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  );
+
+  // Collect quota-relevant metrics
+  const { count: userCount } = await supabase
+    .from('profiles')
+    .select('*', { count: 'exact', head: true });
+
+  const { count: storageObjects } = await supabase
+    .storage.from('uploads')
+    .list('', { limit: 1, offset: 0 })
+    .then(({ data }) => ({ count: data?.length ?? 0 }));
+
+  const { data: dbSize } = await supabase
+    .rpc('get_database_size');
+
+  const metrics = {
+    timestamp: new Date().toISOString(),
+    user_count: userCount,
+    db_size_mb: dbSize,
+    storage_objects: storageObjects,
+  };
+
+  // Store metrics for trend analysis
+  await supabase.from('app_metrics').insert(metrics);
+
+  // Alert on quota thresholds
+  const DB_LIMIT_MB = 8000; // 8GB Pro plan limit
+  if (dbSize > DB_LIMIT_MB * 0.85) {
+    console.warn(`[QUOTA_ALERT] Database at ${Math.round(dbSize / DB_LIMIT_MB * 100)}% capacity`);
+    // Send alert via webhook, email, or Slack
+  }
+
+  return new Response(JSON.stringify(metrics), {
+    headers: { 'Content-Type': 'application/json' },
   });
-}
+});
 ```
 
-## Alert Configuration
-
-### Prometheus AlertManager Rules
-
-```yaml
-# supabase_alerts.yaml
-groups:
-  - name: supabase_alerts
-    rules:
-      - alert: SupabaseHighErrorRate
-        expr: |
-          rate(supabase_errors_total[5m]) /
-          rate(supabase_requests_total[5m]) > 0.05
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Supabase error rate > 5%"
-
-      - alert: SupabaseHighLatency
-        expr: |
-          histogram_quantile(0.95,
-            rate(supabase_request_duration_seconds_bucket[5m])
-          ) > 2
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Supabase P95 latency > 2s"
-
-      - alert: SupabaseDown
-        expr: up{job="supabase"} == 0
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Supabase integration is down"
-```
+Schedule it with a cron trigger in `supabase/config.toml`:
 
-## Dashboard
-
-### Grafana Panel Queries
-
-```json
-{
-  "panels": [
-    {
-      "title": "Supabase Request Rate",
-      "targets": [{
-        "expr": "rate(supabase_requests_total[5m])"
-      }]
-    },
-    {
-      "title": "Supabase Latency P50/P95/P99",
-      "targets": [{
-        "expr": "histogram_quantile(0.5, rate(supabase_request_duration_seconds_bucket[5m]))"
-      }]
-    }
-  ]
-}
+```toml
+[functions.collect-metrics]
+schedule = "*/15 * * * *"  # Every 15 minutes
 ```
 
-## Instructions
-
-### Step 1: Set Up Metrics Collection
-Implement Prometheus counters, histograms, and gauges for key operations.
+**Health check endpoint** for uptime monitoring (Uptime Robot, Pingdom, etc.):
 
-### Step 2: Add Distributed Tracing
-Integrate OpenTelemetry for end-to-end request tracing.
+```typescript
+// supabase/functions/health/index.ts
+import { createClient } from '@supabase/supabase-js';
+import { serve } from 'https://deno.land/std@0.177.0/http/server.ts';
+
+serve(async () => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  );
+
+  const checks: Record<string, { status: string; latency_ms: number; detail?: string }> = {};
+
+  // Database check
+  const dbStart = Date.now();
+  const { error: dbErr } = await supabase.rpc('version');
+  checks.database = {
+    status: dbErr ? 'unhealthy' : 'healthy',
+    latency_ms: Date.now() - dbStart,
+    ...(dbErr && { detail: dbErr.message }),
+  };
+
+  // Auth check
+  const authStart = Date.now();
+  const { error: authErr } = await supabase.auth.admin.listUsers({ perPage: 1 });
+  checks.auth = {
+    status: authErr ? 'unhealthy' : 'healthy',
+    latency_ms: Date.now() - authStart,
+  };
+
+  // Storage check
+  const storageStart = Date.now();
+  const { error: storageErr } = await supabase.storage.listBuckets();
+  checks.storage = {
+    status: storageErr ? 'unhealthy' : 'healthy',
+    latency_ms: Date.now() - storageStart,
+  };
+
+  const overall = Object.values(checks).every(c => c.status === 'healthy');
+  const statusCode = overall ? 200 : 503;
+
+  return new Response(
+    JSON.stringify({ status: overall ? 'healthy' : 'degraded', checks, timestamp: new Date().toISOString() }),
+    { status: statusCode, headers: { 'Content-Type': 'application/json' } }
+  );
+});
+```
 
-### Step 3: Configure Structured Logging
-Set up JSON logging with consistent field names.
+**Real-time connection monitoring** — track active Realtime connections:
 
-### Step 4: Create Alert Rules
-Define Prometheus alerting rules for error rates and latency.
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+// Monitor channel state changes
+const channel = supabase.channel('monitoring');
+
+channel
+  .on('system', { event: '*' }, (payload) => {
+    console.log(`[REALTIME] System event:`, payload);
+  })
+  .subscribe((status) => {
+    console.log(`[REALTIME] Connection status: ${status}`);
+    if (status === 'CHANNEL_ERROR') {
+      console.error('[REALTIME] Connection lost — will auto-reconnect');
+    }
+  });
+```
 
 ## Output
-- Metrics collection enabled
-- Distributed tracing configured
-- Structured logging implemented
-- Alert rules deployed
+
+- Dashboard reports configured for API, database, and auth monitoring
+- CLI inspect commands available for Postgres diagnostics (table sizes, index usage, cache hits, sequential scans, long-running queries)
+- `pg_stat_statements` enabled with slow-query and high-frequency-query views
+- Log drains forwarding to external tools (Datadog, Logflare, or webhook)
+- Custom metrics Edge Function collecting quota-relevant data on a schedule
+- Health check endpoint returning per-service status with latency
+- Alerting on quota thresholds (database size, user count)
 
 ## Error Handling
+
 | Issue | Cause | Solution |
 |-------|-------|----------|
-| Missing metrics | No instrumentation | Wrap client calls |
-| Trace gaps | Missing propagation | Check context headers |
-| Alert storms | Wrong thresholds | Tune alert rules |
-| High cardinality | Too many labels | Reduce label values |
+| `pg_stat_statements` returns no rows | Extension not enabled | Enable via Dashboard > Database > Extensions |
+| `supabase inspect db` fails | CLI not linked to project | Run `supabase link --project-ref <ref>` |
+| Log drain not receiving events | API key invalid or region mismatch | Verify credentials; check `supabase log-drains list` |
+| Cache hit ratio below 95% | Working set exceeds RAM | Upgrade compute add-on or optimize queries |
+| Health check returns 503 | One or more services degraded | Check `detail` field in response; verify service role key |
+| Edge Function cron not firing | Missing `schedule` in config.toml | Add `[functions.<name>]` with `schedule` field and redeploy |
+| Long-running queries growing | Missing indexes or lock contention | Run `inspect db seq-scans` and `inspect db blocking` |
 
 ## Examples
 
-### Quick Metrics Endpoint
-```typescript
-app.get('/metrics', async (req, res) => {
-  res.set('Content-Type', registry.contentType);
-  res.send(await registry.metrics());
-});
+### Quick Diagnostic Script
+
+```bash
+#!/bin/bash
+# supabase-health-check.sh — run all inspect commands at once
+echo "=== Table Sizes ==="
+npx supabase inspect db table-sizes --linked
+echo ""
+echo "=== Cache Hit Ratio ==="
+npx supabase inspect db cache-hit --linked
+echo ""
+echo "=== Sequential Scans ==="
+npx supabase inspect db seq-scans --linked
+echo ""
+echo "=== Long Running Queries ==="
+npx supabase inspect db long-running-queries --linked
+echo ""
+echo "=== Index Usage ==="
+npx supabase inspect db index-usage --linked
+```
+
+### Metrics Table Schema
+
+```sql
+create table if not exists app_metrics (
+  id bigint generated always as identity primary key,
+  timestamp timestamptz not null default now(),
+  user_count integer,
+  db_size_mb numeric,
+  storage_objects integer,
+  api_requests_24h integer,
+  avg_response_ms numeric
+);
+
+-- Index for time-series queries
+create index idx_app_metrics_timestamp on app_metrics (timestamp desc);
+
+-- Retention policy: keep 90 days
+create or replace function cleanup_old_metrics()
+returns void as $$
+  delete from app_metrics where timestamp < now() - interval '90 days';
+$$ language sql;
 ```
 
 ## Resources
-- [Prometheus Best Practices](https://prometheus.io/docs/practices/naming/)
-- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
-- [Supabase Observability Guide](https://supabase.com/docs/observability)
+
+- [Supabase Logs & Analytics](https://supabase.com/docs/guides/platform/logs)
+- [Database Inspect Commands](https://supabase.com/docs/guides/database/inspect)
+- [Log Drains](https://supabase.com/docs/guides/platform/log-drains)
+- [Edge Functions Scheduling](https://supabase.com/docs/guides/functions/schedule-functions)
+- [pg_stat_statements](https://supabase.com/docs/guides/database/extensions/pg_stat_statements)
+- [Supabase JS Client](https://supabase.com/docs/reference/javascript/introduction)
 
 ## Next Steps
-For incident response, see `supabase-incident-runbook`.
+
+For incident response procedures, see `supabase-incident-runbook`.
+For performance optimization, see `supabase-performance-tuning`.

package/skills/supabase-observability/references/alert-configuration.md

@@ -0,0 +1,40 @@
+# Alert Configuration
+
+## Alert Configuration
+
+### Prometheus AlertManager Rules
+
+```yaml
+# supabase_alerts.yaml
+groups:
+  - name: supabase_alerts
+    rules:
+      - alert: SupabaseHighErrorRate
+        expr: |
+          rate(supabase_errors_total[5m]) /
+          rate(supabase_requests_total[5m]) > 0.05
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Supabase error rate > 5%"
+
+      - alert: SupabaseHighLatency
+        expr: |
+          histogram_quantile(0.95,
+            rate(supabase_request_duration_seconds_bucket[5m])
+          ) > 2
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Supabase P95 latency > 2s"
+
+      - alert: SupabaseDown
+        expr: up{job="supabase"} == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Supabase integration is down"
+```

package/skills/supabase-observability/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Missing metrics | No instrumentation | Wrap client calls |
+| Trace gaps | Missing propagation | Check context headers |
+| Alert storms | Wrong thresholds | Tune alert rules |
+| High cardinality | Too many labels | Reduce label values |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/supabase-observability/references/examples.md

@@ -0,0 +1,13 @@
+## Examples
+
+### Quick Metrics Endpoint
+
+```typescript
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', registry.contentType);
+  res.send(await registry.metrics());
+});
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*