@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-advanced-troubleshooting/SKILL.md

@@ -1,261 +1,465 @@
 ---
 name: supabase-advanced-troubleshooting
-description: |
-  Apply Supabase advanced debugging techniques for hard-to-diagnose issues.
-  Use when standard troubleshooting fails, investigating complex race conditions,
-  or preparing evidence bundles for Supabase support escalation.
-  Trigger with phrases like "supabase hard bug", "supabase mystery error",
-  "supabase impossible to debug", "difficult supabase issue", "supabase deep debug".
-allowed-tools: Read, Grep, Bash(kubectl:*), Bash(curl:*), Bash(tcpdump:*)
-version: 1.0.0
-license: MIT
-author: Jeremy Longshore <jeremy@intentsolutions.io>
----
+description: 'Deep Supabase diagnostics: pg_stat_statements for slow queries, lock
+  debugging with
 
-# Supabase Advanced Troubleshooting
-
-## Overview
-Deep debugging techniques for complex Supabase issues that resist standard troubleshooting.
-
-## Prerequisites
-- Access to production logs and metrics
-- kubectl access to clusters
-- Network capture tools available
-- Understanding of distributed tracing
+  pg_locks, connection leak detection, RLS policy conflicts, Edge Function cold starts,
 
-## Evidence Collection Framework
+  and Realtime connection drop analysis.
 
-### Comprehensive Debug Bundle
-```bash
-#!/bin/bash
-# advanced-supabase-debug.sh
+  Use when standard troubleshooting fails, investigating performance regressions,
+  debugging
 
-BUNDLE="supabase-advanced-debug-$(date +%Y%m%d-%H%M%S)"
-mkdir -p "$BUNDLE"/{logs,metrics,network,config,traces}
+  race conditions, or building evidence for Supabase support escalation.
 
-# 1. Extended logs (1 hour window)
-kubectl logs -l app=supabase-integration --since=1h > "$BUNDLE/logs/pods.log"
-journalctl -u supabase-service --since "1 hour ago" > "$BUNDLE/logs/system.log"
+  Trigger: "supabase deep debug", "supabase slow query", "supabase lock contention",
 
-# 2. Metrics dump
-curl -s localhost:9090/api/v1/query?query=supabase_requests_total > "$BUNDLE/metrics/requests.json"
-curl -s localhost:9090/api/v1/query?query=supabase_errors_total > "$BUNDLE/metrics/errors.json"
+  "supabase connection leak", "supabase RLS conflict", "supabase cold start".
 
-# 3. Network capture (30 seconds)
-timeout 30 tcpdump -i any port 443 -w "$BUNDLE/network/capture.pcap" &
-
-# 4. Distributed traces
-curl -s localhost:16686/api/traces?service=supabase > "$BUNDLE/traces/jaeger.json"
-
-# 5. Configuration state
-kubectl get cm supabase-config -o yaml > "$BUNDLE/config/configmap.yaml"
-kubectl get secret supabase-secrets -o yaml > "$BUNDLE/config/secrets-redacted.yaml"
-
-tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
-echo "Advanced debug bundle: $BUNDLE.tar.gz"
-```
-
-## Systematic Isolation
-
-### Layer-by-Layer Testing
+  '
+allowed-tools: Read, Grep, Bash(npx supabase:*), Bash(supabase:*), Bash(curl:*), Bash(psql:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- debugging
+- advanced
+- performance
+- troubleshooting
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
+---
+# Supabase Advanced Troubleshooting
 
-```typescript
-// Test each layer independently
-async function diagnoseSupabaseIssue(): Promise<DiagnosisReport> {
-  const results: DiagnosisResult[] = [];
+## Overview
 
-  // Layer 1: Network connectivity
-  results.push(await testNetworkConnectivity());
+When basic debugging does not reveal the root cause, you need deep PostgreSQL diagnostics: `pg_stat_statements` to find the slowest queries by cumulative execution time, `pg_locks` to detect lock contention and deadlocks, `pg_stat_activity` to find connection leaks, RLS policy conflict analysis to diagnose silent data filtering, Edge Function cold start profiling, and Realtime channel drop investigation. This skill covers every advanced diagnostic technique with real SQL queries and `createClient` from `@supabase/supabase-js`.
 
-  // Layer 2: DNS resolution
-  results.push(await testDNSResolution('api.supabase.com'));
+**When to use:** Slow query investigation, lock contention causing timeouts, connection pool exhaustion from leaks, RLS policies that silently filter or conflict, Edge Functions with unpredictable latency, or Realtime subscriptions that disconnect intermittently.
 
-  // Layer 3: TLS handshake
-  results.push(await testTLSHandshake('api.supabase.com'));
+## Prerequisites
 
-  // Layer 4: Authentication
-  results.push(await testAuthentication());
+- Supabase project with `pg_stat_statements` extension enabled
+- Direct database access via SQL Editor or `psql`
+- `@supabase/supabase-js` v2+ installed in your project
+- Supabase CLI for Edge Function logs
+- Familiarity with PostgreSQL system catalogs
 
-  // Layer 5: API response
-  results.push(await testAPIResponse());
+## Instructions
 
-  // Layer 6: Response parsing
-  results.push(await testResponseParsing());
+### Step 1: pg_stat_statements and Slow Query Analysis
+
+Enable and query `pg_stat_statements` to find the most expensive queries by total execution time, calls, and rows processed.
+
+**Enable the extension and query slow queries:**
+
+```sql
+-- Enable pg_stat_statements (run once)
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Top 10 slowest queries by total execution time
+SELECT
+  queryid,
+  calls,
+  round(total_exec_time::numeric, 2) AS total_ms,
+  round(mean_exec_time::numeric, 2) AS avg_ms,
+  round(max_exec_time::numeric, 2) AS max_ms,
+  rows AS total_rows,
+  round(100.0 * shared_blks_hit / nullif(shared_blks_hit + shared_blks_read, 0), 2) AS cache_hit_pct,
+  left(query, 150) AS query_preview
+FROM pg_stat_statements
+WHERE userid = (SELECT usesysid FROM pg_user WHERE usename = current_user)
+ORDER BY total_exec_time DESC
+LIMIT 10;
+
+-- Top queries by frequency (most called)
+SELECT
+  queryid,
+  calls,
+  round(mean_exec_time::numeric, 2) AS avg_ms,
+  rows / nullif(calls, 0) AS rows_per_call,
+  left(query, 150) AS query_preview
+FROM pg_stat_statements
+WHERE calls > 100
+ORDER BY calls DESC
+LIMIT 10;
+
+-- Queries with poor cache hit ratio (reading from disk)
+SELECT
+  queryid,
+  calls,
+  shared_blks_hit,
+  shared_blks_read,
+  round(100.0 * shared_blks_hit / nullif(shared_blks_hit + shared_blks_read, 0), 2) AS cache_hit_pct,
+  left(query, 150) AS query_preview
+FROM pg_stat_statements
+WHERE shared_blks_read > 100
+ORDER BY shared_blks_read DESC
+LIMIT 10;
+
+-- Reset statistics after optimization (to measure improvement)
+-- SELECT pg_stat_statements_reset();
+```
 
-  return { results, firstFailure: results.find(r => !r.success) };
-}
+**EXPLAIN ANALYZE for specific slow queries:**
+
+```sql
+-- Run EXPLAIN ANALYZE on the suspicious query
+EXPLAIN (ANALYZE, BUFFERS, TIMING, FORMAT TEXT)
+SELECT p.*, count(o.id) AS order_count
+FROM profiles p
+LEFT JOIN orders o ON o.user_id = p.id
+WHERE p.created_at > now() - interval '30 days'
+GROUP BY p.id
+ORDER BY order_count DESC
+LIMIT 50;
+
+-- What to look for in the output:
+-- 1. Seq Scan on large table → needs an index
+-- 2. Nested Loop with high actual rows → consider Hash Join
+-- 3. Sort with "Sort Method: external merge" → increase work_mem or add index
+-- 4. Buffers read >> shared hit → data not cached, optimize query or increase shared_buffers
+
+-- Create a targeted index based on EXPLAIN output
+CREATE INDEX CONCURRENTLY idx_profiles_created_at
+  ON profiles(created_at DESC);
+
+CREATE INDEX CONCURRENTLY idx_orders_user_id
+  ON orders(user_id);
 ```
 
-### Minimal Reproduction
+**Monitor query performance from the SDK:**
 
 ```typescript
-// Strip down to absolute minimum
-async function minimalRepro(): Promise<void> {
-  // 1. Fresh client, no customization
-  const client = new SupabaseClient({
-    apiKey: process.env.SUPABASE_API_KEY!,
-  });
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+
+// Wrapper that measures and logs query performance
+async function timedQuery<T>(
+  label: string,
+  queryFn: () => Promise<{ data: T | null; error: any }>
+): Promise<T | null> {
+  const start = performance.now();
+  const { data, error } = await queryFn();
+  const duration = Math.round(performance.now() - start);
+
+  if (duration > 500) {
+    console.warn(`[SLOW QUERY] ${label}: ${duration}ms`);
+  }
 
-  // 2. Simplest possible call
-  try {
-    const result = await client.ping();
-    console.log('Ping successful:', result);
-  } catch (error) {
-    console.error('Ping failed:', {
-      message: error.message,
-      code: error.code,
-      stack: error.stack,
-    });
+  if (error) {
+    console.error(`[QUERY ERROR] ${label}:`, error.message);
+    return null;
   }
+
+  return data;
 }
-```
 
-## Timing Analysis
+// Usage
+const profiles = await timedQuery('recent-profiles', () =>
+  supabase
+    .from('profiles')
+    .select('*, orders(count)')
+    .gte('created_at', new Date(Date.now() - 30 * 86400000).toISOString())
+    .order('created_at', { ascending: false })
+    .limit(50)
+);
+```
 
-```typescript
-class TimingAnalyzer {
-  private timings: Map<string, number[]> = new Map();
-
-  async measure<T>(label: string, fn: () => Promise<T>): Promise<T> {
-    const start = performance.now();
-    try {
-      return await fn();
-    } finally {
-      const duration = performance.now() - start;
-      const existing = this.timings.get(label) || [];
-      existing.push(duration);
-      this.timings.set(label, existing);
-    }
-  }
+### Step 2: Lock Debugging and Connection Leak Detection
+
+Find blocked queries, detect lock contention, and identify connection leaks that exhaust the pool.
+
+**Lock contention detection:**
+
+```sql
+-- Find blocked queries and what's blocking them
+SELECT
+  blocked.pid AS blocked_pid,
+  blocked.usename AS blocked_user,
+  age(now(), blocked.query_start)::text AS blocked_duration,
+  left(blocked.query, 100) AS blocked_query,
+  blocking.pid AS blocking_pid,
+  blocking.usename AS blocking_user,
+  left(blocking.query, 100) AS blocking_query,
+  bl.mode AS lock_mode
+FROM pg_stat_activity blocked
+JOIN pg_locks bl ON bl.pid = blocked.pid AND NOT bl.granted
+JOIN pg_locks kl ON kl.locktype = bl.locktype
+  AND kl.database IS NOT DISTINCT FROM bl.database
+  AND kl.relation IS NOT DISTINCT FROM bl.relation
+  AND kl.page IS NOT DISTINCT FROM bl.page
+  AND kl.tuple IS NOT DISTINCT FROM bl.tuple
+  AND kl.pid != bl.pid
+  AND kl.granted
+JOIN pg_stat_activity blocking ON blocking.pid = kl.pid
+WHERE blocked.state = 'active';
+
+-- Check all locks on a specific table
+SELECT
+  l.locktype, l.mode, l.granted, l.pid,
+  a.usename, a.state,
+  age(now(), a.query_start)::text AS duration,
+  left(a.query, 80) AS query
+FROM pg_locks l
+JOIN pg_stat_activity a ON a.pid = l.pid
+WHERE l.relation = 'orders'::regclass
+ORDER BY l.granted, a.query_start;
+
+-- Detect potential deadlocks
+SELECT
+  l1.pid AS pid1, l2.pid AS pid2,
+  l1.mode AS lock1, l2.mode AS lock2,
+  l1.relation::regclass AS table1,
+  l2.relation::regclass AS table2
+FROM pg_locks l1
+JOIN pg_locks l2 ON l1.pid != l2.pid
+  AND l1.relation = l2.relation
+  AND NOT l1.granted AND l2.granted
+WHERE l1.locktype = 'relation';
+```
 
-  report(): TimingReport {
-    const report: TimingReport = {};
-    for (const [label, times] of this.timings) {
-      report[label] = {
-        count: times.length,
-        min: Math.min(...times),
-        max: Math.max(...times),
-        avg: times.reduce((a, b) => a + b, 0) / times.length,
-        p95: this.percentile(times, 95),
-      };
-    }
-    return report;
-  }
-}
+**Connection leak detection:**
+
+```sql
+-- Connections that have been idle for too long (likely leaks)
+SELECT
+  pid, usename, client_addr, state,
+  age(now(), state_change)::text AS idle_time,
+  age(now(), backend_start)::text AS connection_age,
+  left(query, 100) AS last_query
+FROM pg_stat_activity
+WHERE state = 'idle'
+  AND age(now(), state_change) > interval '5 minutes'
+  AND datname = current_database()
+ORDER BY state_change;
+
+-- Connections stuck in "idle in transaction" (the worst kind of leak)
+SELECT
+  pid, usename, client_addr,
+  age(now(), xact_start)::text AS transaction_duration,
+  age(now(), state_change)::text AS idle_in_tx_time,
+  left(query, 100) AS last_query
+FROM pg_stat_activity
+WHERE state = 'idle in transaction'
+ORDER BY xact_start;
+
+-- Connection usage by application/user
+SELECT
+  usename,
+  client_addr,
+  state,
+  count(*) AS connections
+FROM pg_stat_activity
+WHERE datname = current_database()
+GROUP BY usename, client_addr, state
+ORDER BY connections DESC;
+
+-- Kill leaked connections (batch)
+-- SELECT pg_terminate_backend(pid)
+-- FROM pg_stat_activity
+-- WHERE state = 'idle in transaction'
+--   AND age(now(), state_change) > interval '10 minutes';
 ```
 
-## Memory and Resource Analysis
+**Connection pool monitoring from the SDK:**
 
 ```typescript
-// Detect memory leaks in Supabase client usage
-const heapUsed: number[] = [];
-
-setInterval(() => {
-  const usage = process.memoryUsage();
-  heapUsed.push(usage.heapUsed);
-
-  // Alert on sustained growth
-  if (heapUsed.length > 60) { // 1 hour at 1/min
-    const trend = heapUsed[59] - heapUsed[0];
-    if (trend > 100 * 1024 * 1024) { // 100MB growth
-      console.warn('Potential memory leak in supabase integration');
-    }
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+
+// Monitor connection pool health
+async function checkConnectionPool() {
+  const { data, error } = await supabase.rpc('get_connection_health');
+  if (error) {
+    console.error('Connection health check failed:', error.message);
+    return;
   }
-}, 60000);
-```
 
-## Race Condition Detection
+  const health = data as {
+    active: number;
+    idle: number;
+    idle_in_transaction: number;
+    total: number;
+    max_connections: number;
+  };
 
-```typescript
-// Detect concurrent access issues
-class SupabaseConcurrencyChecker {
-  private inProgress: Set<string> = new Set();
+  const utilization = (health.total / health.max_connections) * 100;
 
-  async execute<T>(key: string, fn: () => Promise<T>): Promise<T> {
-    if (this.inProgress.has(key)) {
-      console.warn(`Concurrent access detected for ${key}`);
-    }
+  console.log('Connection pool:', {
+    ...health,
+    utilization: `${utilization.toFixed(1)}%`,
+  });
 
-    this.inProgress.add(key);
-    try {
-      return await fn();
-    } finally {
-      this.inProgress.delete(key);
-    }
+  if (health.idle_in_transaction > 0) {
+    console.warn(`WARNING: ${health.idle_in_transaction} idle-in-transaction connections (likely leaks)`);
+  }
+
+  if (utilization > 80) {
+    console.warn(`WARNING: Connection pool at ${utilization.toFixed(1)}% capacity`);
   }
 }
+
+// Database function for the RPC call:
+// CREATE OR REPLACE FUNCTION get_connection_health()
+// RETURNS json AS $$
+//   SELECT json_build_object(
+//     'active', (SELECT count(*) FROM pg_stat_activity WHERE state = 'active' AND datname = current_database()),
+//     'idle', (SELECT count(*) FROM pg_stat_activity WHERE state = 'idle' AND datname = current_database()),
+//     'idle_in_transaction', (SELECT count(*) FROM pg_stat_activity WHERE state = 'idle in transaction' AND datname = current_database()),
+//     'total', (SELECT count(*) FROM pg_stat_activity WHERE datname = current_database()),
+//     'max_connections', (SELECT setting::int FROM pg_settings WHERE name = 'max_connections')
+//   );
+// $$ LANGUAGE sql SECURITY DEFINER;
 ```
 
-## Support Escalation Template
+### Step 3: RLS Conflicts, Edge Function Cold Starts, and Realtime Drops
 
-```markdown
-## Supabase Support Escalation
+See [RLS conflicts, Edge Function cold starts, and Realtime drops](references/rls-edge-functions-realtime.md) for RLS policy conflict analysis (SQL and SDK), Edge Function cold start profiling, Realtime channel monitoring, and publication configuration.
 
-**Severity:** P[1-4]
-**Request ID:** [from error response]
-**Timestamp:** [ISO 8601]
+## Output
 
-### Issue Summary
-[One paragraph description]
+After completing this skill, you will have:
 
-### Steps to Reproduce
-1. [Step 1]
-2. [Step 2]
+- **Slow query identification** — `pg_stat_statements` queries ranking by total time, frequency, and cache hit ratio
+- **EXPLAIN ANALYZE proficiency** — reading execution plans and creating targeted indexes
+- **Lock contention diagnosis** — blocked/blocking query pairs with lock modes
+- **Connection leak detection** — idle and idle-in-transaction connections with kill commands
+- **Connection pool monitoring** — SDK-based health check RPC with utilization alerts
+- **RLS conflict analysis** — policy listing with permissive/restrictive classification and multi-level comparison
+- **Edge Function profiling** — cold start vs warm invocation measurement
+- **Realtime debugging** — channel state monitoring with system event logging
 
-### Expected vs Actual
-- Expected: [behavior]
-- Actual: [behavior]
+## Error Handling
 
-### Evidence Attached
-- [ ] Debug bundle (supabase-advanced-debug-*.tar.gz)
-- [ ] Minimal reproduction code
-- [ ] Timing analysis
-- [ ] Network capture (if relevant)
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `pg_stat_statements` not available | Extension not enabled | Run `CREATE EXTENSION pg_stat_statements;` |
+| Seq Scan on large table | Missing index on filter column | Create index with `CREATE INDEX CONCURRENTLY` |
+| `deadlock detected` | Circular lock dependency | Ensure consistent lock ordering across transactions |
+| All connections in `idle in transaction` | Application not closing transactions | Add connection timeout; review ORM connection pool settings |
+| RLS returns empty for authenticated user | JWT claims don't match policy | Check `auth.jwt()` output; verify `app_metadata` is set |
+| Edge Function > 2s cold start | Large dependency bundle | Lazy-import heavy modules; reduce function size |
+| Realtime `TIMED_OUT` | Network/firewall blocking WebSocket | Check port 443 is open; verify no proxy strips `Upgrade` header |
+| `CHANNEL_ERROR` on subscribe | Table not in Realtime publication | Run `ALTER PUBLICATION supabase_realtime ADD TABLE ...` |
 
-### Workarounds Attempted
-1. [Workaround 1] - Result: [outcome]
-2. [Workaround 2] - Result: [outcome]
-```
+## Examples
 
-## Instructions
+**Example 1 — Quick performance audit:**
+
+```sql
+-- Run this query to get a snapshot of database health
+SELECT
+  'Connections' AS metric,
+  count(*)::text AS value
+FROM pg_stat_activity WHERE datname = current_database()
+UNION ALL
+SELECT 'Cache hit ratio',
+  round(100.0 * sum(heap_blks_hit) / nullif(sum(heap_blks_hit + heap_blks_read), 0), 2)::text || '%'
+FROM pg_statio_user_tables
+UNION ALL
+SELECT 'Table bloat (dead tuples)',
+  sum(n_dead_tup)::text
+FROM pg_stat_user_tables
+UNION ALL
+SELECT 'Longest running query',
+  coalesce(max(age(now(), query_start))::text, 'none')
+FROM pg_stat_activity WHERE state = 'active' AND query NOT LIKE '%pg_stat%';
+```
 
-### Step 1: Collect Evidence Bundle
-Run the comprehensive debug script to gather all relevant data.
+**Example 2 — Build a diagnostic bundle for support:**
 
-### Step 2: Systematic Isolation
-Test each layer independently to identify the failure point.
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(url, serviceRoleKey, {
+  auth: { autoRefreshToken: false, persistSession: false },
+});
+
+async function buildDiagnosticBundle() {
+  const bundle: Record<string, any> = {
+    timestamp: new Date().toISOString(),
+    projectRef: process.env.SUPABASE_PROJECT_REF,
+  };
+
+  // Connection stats
+  const { data: connHealth } = await supabase.rpc('get_connection_health');
+  bundle.connections = connHealth;
+
+  // Table sizes
+  const { data: tableSizes } = await supabase.rpc('get_table_sizes');
+  bundle.tableSizes = tableSizes;
+
+  // Recent errors from application logs
+  const { data: recentErrors } = await supabase
+    .from('error_logs')
+    .select('message, count, last_seen')
+    .order('last_seen', { ascending: false })
+    .limit(10);
+  bundle.recentErrors = recentErrors;
+
+  console.log(JSON.stringify(bundle, null, 2));
+  // Submit with your support ticket at https://supabase.com/dashboard/support
+}
+```
 
-### Step 3: Create Minimal Reproduction
-Strip down to the simplest failing case.
+**Example 3 — Automated slow query alert:**
 
-### Step 4: Escalate with Evidence
-Use the support template with all collected evidence.
+```typescript
+import { createClient } from '@supabase/supabase-js';
 
-## Output
-- Comprehensive debug bundle collected
-- Failure layer identified
-- Minimal reproduction created
-- Support escalation submitted
+const supabase = createClient(url, serviceRoleKey, {
+  auth: { autoRefreshToken: false, persistSession: false },
+});
 
-## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Can't reproduce | Race condition | Add timing analysis |
-| Intermittent failure | Timing-dependent | Increase sample size |
-| No useful logs | Missing instrumentation | Add debug logging |
-| Memory growth | Resource leak | Use heap profiling |
+async function checkSlowQueries(thresholdMs = 1000) {
+  const { data: slowQueries } = await supabase.rpc('get_slow_queries', {
+    threshold_ms: thresholdMs,
+  });
 
-## Examples
+  if (slowQueries && slowQueries.length > 0) {
+    console.warn(`Found ${slowQueries.length} queries averaging > ${thresholdMs}ms`);
+    for (const q of slowQueries) {
+      console.warn(`  [${q.avg_ms}ms avg, ${q.calls} calls] ${q.query_preview}`);
+    }
+  }
+}
 
-### Quick Layer Test
-```bash
-# Test each layer in sequence
-curl -v https://api.supabase.com/health 2>&1 | grep -E "(Connected|TLS|HTTP)"
+// Database function:
+// CREATE OR REPLACE FUNCTION get_slow_queries(threshold_ms numeric DEFAULT 1000)
+// RETURNS TABLE(queryid bigint, avg_ms numeric, calls bigint, query_preview text) AS $$
+//   SELECT queryid, round(mean_exec_time::numeric, 2), calls, left(query, 150)
+//   FROM pg_stat_statements
+//   WHERE mean_exec_time > threshold_ms AND calls > 10
+//   ORDER BY mean_exec_time DESC LIMIT 10;
+// $$ LANGUAGE sql SECURITY DEFINER;
 ```
 
 ## Resources
-- [Supabase Support Portal](https://support.supabase.com)
-- [Supabase Status Page](https://status.supabase.com)
+
+- [pg_stat_statements — PostgreSQL Docs](https://www.postgresql.org/docs/current/pgstatstatements.html)
+- [EXPLAIN ANALYZE — PostgreSQL Docs](https://www.postgresql.org/docs/current/sql-explain.html)
+- [Supabase Performance Advisor](https://supabase.com/docs/guides/database/inspect)
+- [RLS Debugging — Supabase Docs](https://supabase.com/docs/guides/troubleshooting/rls-simplified-BJTcS8)
+- [Edge Functions Logging — Supabase Docs](https://supabase.com/docs/guides/functions/logging)
+- Realtime Debugging — Supabase Docs
+- [pg_locks — PostgreSQL Docs](https://www.postgresql.org/docs/current/view-pg-locks.html)
+- [Connection Pooling with Supavisor](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)
 
 ## Next Steps
-For load testing, see `supabase-load-scale`.
+
+- For load testing and scaling patterns, see `supabase-load-scale`
+- For incident response procedures, see `supabase-incident-runbook`
+- For performance tuning and index optimization, see `supabase-performance-tuning`
+- For common error patterns and quick fixes, see `supabase-common-errors`