@intentsolutionsio/supabase-pack 1.0.0 → 1.0.3

package/skills/supabase-prod-checklist/SKILL.md

@@ -1,119 +1,509 @@
 ---
 name: supabase-prod-checklist
-description: |
-  Execute Supabase production deployment checklist and rollback procedures.
-  Use when deploying Supabase integrations to production, preparing for launch,
-  or implementing go-live procedures.
-  Trigger with phrases like "supabase production", "deploy supabase",
-  "supabase go-live", "supabase launch checklist".
-allowed-tools: Read, Bash(kubectl:*), Bash(curl:*), Grep
+description: 'Execute Supabase production deployment checklist covering RLS, key hygiene,
+
+  connection pooling, backups, monitoring, Edge Functions, and Storage policies.
+
+  Use when deploying to production, preparing for launch,
+
+  or auditing a live Supabase project for security and performance gaps.
+
+  Trigger with "supabase production", "supabase go-live",
+
+  "supabase launch checklist", "supabase prod ready", "deploy supabase",
+
+  "supabase production readiness".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(npx supabase:*), Bash(curl:*), Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- supabase
+- deployment
+- production
+- security
+- rls
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
-# Supabase Production Checklist
+# Supabase Production Deployment Checklist
 
 ## Overview
-Complete checklist for deploying Supabase integrations to production.
+
+Actionable 14-step checklist for taking a Supabase project to production. Covers RLS enforcement, key separation, connection pooling (Supavisor), backups/PITR, network restrictions, custom domains, auth emails, rate limits, monitoring, Edge Functions, Storage policies, indexes, and migrations. Based on Supabase's official [production guide](https://supabase.com/docs/guides/deployment/going-into-prod).
 
 ## Prerequisites
-- Staging environment tested and verified
-- Production API keys available
-- Deployment pipeline configured
-- Monitoring and alerting ready
+
+- Supabase project on Pro plan or higher (required for PITR, network restrictions)
+- Separate production project (never share dev/prod)
+- `@supabase/supabase-js` v2+ installed
+- Supabase CLI installed (`npx supabase --version`)
+- Domain and DNS configured for custom domain
+- Deployment platform ready (Vercel, Netlify, Cloudflare, etc.)
 
 ## Instructions
 
-### Step 1: Pre-Deployment Configuration
-- [ ] Production API keys in secure vault
-- [ ] Environment variables set in deployment platform
-- [ ] API key scopes are minimal (least privilege)
-- [ ] Webhook endpoints configured with HTTPS
-- [ ] Webhook secrets stored securely
-
-### Step 2: Code Quality Verification
-- [ ] All tests passing (`npm test`)
-- [ ] No hardcoded credentials
-- [ ] Error handling covers all Supabase error types
-- [ ] Rate limiting/backoff implemented
-- [ ] Logging is production-appropriate
-
-### Step 3: Infrastructure Setup
-- [ ] Health check endpoint includes Supabase connectivity
-- [ ] Monitoring/alerting configured
-- [ ] Circuit breaker pattern implemented
-- [ ] Graceful degradation configured
-
-### Step 4: Documentation Requirements
-- [ ] Incident runbook created
-- [ ] Key rotation procedure documented
-- [ ] Rollback procedure documented
-- [ ] On-call escalation path defined
-
-### Step 5: Deploy with Gradual Rollout
+### Step 1: Enforce Row Level Security on ALL Tables
+
+RLS is the single most critical production requirement. Without it, any client with your anon key can read/write every row.
+
+```sql
+-- Audit: find tables WITHOUT RLS enabled
+-- This query MUST return zero rows before going live
+SELECT schemaname, tablename, rowsecurity
+FROM pg_tables
+WHERE schemaname = 'public' AND rowsecurity = false;
+```
+
+```sql
+-- Enable RLS on a table
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+
+-- Create a basic read policy (authenticated users see own rows)
+CREATE POLICY "Users can view own profile"
+  ON public.profiles
+  FOR SELECT
+  USING (auth.uid() = user_id);
+
+-- Create an insert policy
+CREATE POLICY "Users can insert own profile"
+  ON public.profiles
+  FOR INSERT
+  WITH CHECK (auth.uid() = user_id);
+
+-- Create an update policy
+CREATE POLICY "Users can update own profile"
+  ON public.profiles
+  FOR UPDATE
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+```
+
+- [ ] RLS enabled on every public table (zero rows from audit query above)
+- [ ] SELECT, INSERT, UPDATE, DELETE policies defined for each table
+- [ ] Policies tested with both authenticated and anonymous roles
+- [ ] No tables use `USING (true)` without intent (public read tables only)
+
+### Step 2: Enforce Key Separation — Anon vs Service Role
+
+The `anon` key is safe for client-side code. The `service_role` key bypasses RLS entirely and must never leave server-side environments.
+
+```typescript
+// Client-side — ONLY use anon key
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!  // Safe for browsers
+);
+```
+
+```typescript
+// Server-side only — service_role key (API routes, webhooks, cron jobs)
+import { createClient } from '@supabase/supabase-js';
+
+const supabaseAdmin = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,  // NEVER expose to client
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+```
+
+- [ ] Anon key used in all client-side code (`NEXT_PUBLIC_` prefix)
+- [ ] Service role key used only in server-side code (API routes, Edge Functions)
+- [ ] Service role key not in any client bundle (verify with `grep -r "service_role" dist/`)
+- [ ] Database password changed from the auto-generated default
+
+### Step 3: Configure Connection Pooling (Supavisor)
+
+Supabase uses Supavisor for connection pooling. Serverless functions (Vercel, Netlify, Cloudflare Workers) MUST use the pooled connection string to avoid exhausting the database connection limit.
+
+```
+# Direct connection (migrations, admin tasks only)
+postgresql://postgres:[PASSWORD]@db.[REF].supabase.co:5432/postgres
+
+# Pooled connection via Supavisor (application code — USE THIS)
+# Port 6543 = Supavisor pooler (vs 5432 direct)
+postgresql://postgres.[REF]:[PASSWORD]@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+```
+
+```typescript
+// For serverless environments — use pooled connection
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!,
+  {
+    db: { schema: 'public' },
+    // Supavisor handles pooling at port 6543
+    // No need to configure pgBouncer settings in the client
+  }
+);
+```
+
+- [ ] Application code uses pooled connection string (port 6543)
+- [ ] Direct connection reserved for migrations and admin tasks only
+- [ ] Connection string in deployment platform env vars (not hardcoded)
+- [ ] Verified pool mode: `transaction` for serverless, `session` for long-lived connections
+
+### Step 4: Enable Database Backups
+
+Supabase provides automatic daily backups on Pro plan. Point-in-time recovery (PITR) enables granular restores.
+
+- [ ] Automatic daily backups enabled (Pro plan — verify in Dashboard > Database > Backups)
+- [ ] Point-in-time recovery configured (Dashboard > Database > Backups > PITR)
+- [ ] Tested restore procedure on a staging project (do not skip this)
+- [ ] Migration files committed to version control (`supabase/migrations/` directory)
+- [ ] `npx supabase db push` tested against a fresh project to verify migrations replay cleanly
+
+### Step 5: Configure Network Restrictions
+
+Restrict database access to known IP addresses. This prevents unauthorized direct database connections even if credentials leak.
+
+- [ ] IP allowlist configured (Dashboard > Database > Network Restrictions)
+- [ ] Only deployment platform IPs and team office IPs are allowed
+- [ ] Verified that application still connects after restrictions applied
+- [ ] Documented which IPs are allowed and why
+
+### Step 6: Configure Custom Domain
+
+A custom domain replaces the default `*.supabase.co` URLs with your brand domain for API and auth endpoints.
+
+- [ ] Custom domain configured (Dashboard > Settings > Custom Domains)
+- [ ] DNS CNAME record added and verified
+- [ ] SSL certificate provisioned and active
+- [ ] Application code updated to use custom domain URL
+- [ ] OAuth redirect URLs updated to use custom domain
+
+### Step 7: Customize Auth Email Templates
+
+Default Supabase auth emails show generic branding. Customize them so users see your domain and brand.
+
+- [ ] Confirmation email template customized (Dashboard > Auth > Email Templates)
+- [ ] Password reset email template customized
+- [ ] Magic link email template customized
+- [ ] Invite email template customized
+- [ ] Custom SMTP configured (Dashboard > Auth > SMTP Settings) — avoids rate limits and improves deliverability
+- [ ] Email confirmation enabled (Dashboard > Auth > Settings)
+- [ ] OAuth redirect URLs restricted to production domains only
+- [ ] Unused auth providers disabled
+
+### Step 8: Understand Rate Limits Per Tier
+
+Supabase enforces rate limits that vary by plan. Hitting these in production causes 429 errors.
+
+| Resource | Free | Pro | Team |
+|----------|------|-----|------|
+| API requests | 500/min | 1,000/min | 5,000/min |
+| Auth emails | 4/hour | 30/hour | 100/hour |
+| Realtime connections | 200 concurrent | 500 concurrent | 2,000 concurrent |
+| Edge Function invocations | 500K/month | 2M/month | 5M/month |
+| Storage bandwidth | 2GB/month | 250GB/month | Custom |
+| Database size | 500MB | 8GB | 50GB |
+
+- [ ] Rate limits documented for your plan tier
+- [ ] Client-side retry logic with exponential backoff for 429 responses
+- [ ] Auth email rate limits understood (use custom SMTP to increase)
+- [ ] Realtime connection limits planned for expected concurrent users
+
+### Step 9: Review Monitoring Dashboards
+
+Supabase provides built-in monitoring. Review these before launch to establish baselines.
+
+```typescript
+// Health check endpoint — deploy this to your application
+import { createClient } from '@supabase/supabase-js';
+
+const supabase = createClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!
+);
+
+export async function GET() {
+  const start = Date.now();
+  const { data, error } = await supabase
+    .from('_health_check')  // Create a small table for this
+    .select('id')
+    .limit(1);
+
+  const latency = Date.now() - start;
+
+  return Response.json({
+    status: error ? 'unhealthy' : 'healthy',
+    latency_ms: latency,
+    timestamp: new Date().toISOString(),
+    supabase_reachable: !error,
+  }, { status: error ? 503 : 200 });
+}
+```
+
+- [ ] Dashboard > Reports reviewed (API requests, auth, storage, realtime)
+- [ ] Dashboard > Logs > API checked for error patterns
+- [ ] Dashboard > Database > Performance Advisor reviewed and recommendations applied
+- [ ] Health check endpoint deployed and monitored (uptime service)
+- [ ] Error tracking configured (Sentry, LogRocket, etc.)
+- [ ] Alerts set for: error rate spikes, high latency, connection pool exhaustion
+
+### Step 10: Deploy Edge Functions with Proper Env Vars
+
+Edge Functions run on Deno Deploy. Environment variables must be set via the Supabase CLI or Dashboard, not hardcoded.
+
+```bash
+# Set secrets for Edge Functions
+npx supabase secrets set STRIPE_SECRET_KEY=sk_live_...
+npx supabase secrets set RESEND_API_KEY=re_...
+
+# List current secrets
+npx supabase secrets list
+
+# Deploy all Edge Functions
+npx supabase functions deploy
+
+# Deploy a specific function
+npx supabase functions deploy process-webhook
+```
+
+```typescript
+// supabase/functions/process-webhook/index.ts
+import { createClient } from '@supabase/supabase-js';
+
+Deno.serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!  // Available automatically
+  );
+
+  const body = await req.json();
+  // Process webhook payload...
+
+  return new Response(JSON.stringify({ received: true }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+});
+```
+
+- [ ] All Edge Functions deployed to production (`npx supabase functions deploy`)
+- [ ] Environment secrets set via `npx supabase secrets set` (not hardcoded)
+- [ ] `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` available automatically (no need to set)
+- [ ] Edge Functions tested with `npx supabase functions serve` locally before deploying
+- [ ] CORS headers configured for Edge Functions that receive browser requests
+
+### Step 11: Verify Storage Bucket Policies
+
+Storage buckets need explicit policies, similar to RLS on tables. Without policies, buckets are inaccessible (default deny).
+
+```sql
+-- Check storage bucket configurations
+SELECT id, name, public, file_size_limit, allowed_mime_types
+FROM storage.buckets;
+
+-- Check existing storage policies
+SELECT policyname, tablename, cmd, qual
+FROM pg_policies
+WHERE schemaname = 'storage';
+```
+
+```sql
+-- Example: Allow authenticated users to upload to their own folder
+CREATE POLICY "Users can upload own files"
+  ON storage.objects
+  FOR INSERT
+  WITH CHECK (
+    bucket_id = 'avatars'
+    AND auth.uid()::text = (storage.foldername(name))[1]
+  );
+
+-- Example: Allow public read access to a bucket
+CREATE POLICY "Public read access"
+  ON storage.objects
+  FOR SELECT
+  USING (bucket_id = 'public-assets');
+```
+
+- [ ] Each bucket has explicit SELECT/INSERT/UPDATE/DELETE policies
+- [ ] Public buckets are intentionally public (not accidentally open)
+- [ ] File size limits set per bucket (`file_size_limit` in bucket config)
+- [ ] Allowed MIME types restricted per bucket (`allowed_mime_types`)
+- [ ] User upload paths scoped to `auth.uid()` to prevent overwrites
+
+### Step 12: Add Database Indexes on Frequently Queried Columns
+
+Missing indexes are the leading cause of slow queries after launch. Add indexes on foreign keys, filter columns, and sort columns.
+
+```sql
+-- Find missing indexes on foreign keys
+SELECT
+  tc.table_name, kcu.column_name,
+  CASE WHEN i.indexname IS NULL THEN '** MISSING INDEX **' ELSE i.indexname END AS index_status
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu
+  ON tc.constraint_name = kcu.constraint_name
+LEFT JOIN pg_indexes i
+  ON i.tablename = tc.table_name
+  AND i.indexdef LIKE '%' || kcu.column_name || '%'
+WHERE tc.constraint_type = 'FOREIGN KEY'
+  AND tc.table_schema = 'public';
+
+-- Find slow queries (requires pg_stat_statements extension)
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+SELECT query, calls, mean_exec_time::numeric(10,2) AS avg_ms,
+       total_exec_time::numeric(10,2) AS total_ms
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 10;
+
+-- Check table bloat (dead tuples from updates/deletes)
+SELECT relname, n_live_tup, n_dead_tup,
+       round(n_dead_tup::numeric / greatest(n_live_tup, 1) * 100, 1) AS dead_pct
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;
+```
+
+```sql
+-- Create indexes on commonly filtered columns
+CREATE INDEX idx_profiles_user_id ON public.profiles(user_id);
+CREATE INDEX idx_orders_created_at ON public.orders(created_at DESC);
+CREATE INDEX idx_posts_status ON public.posts(status) WHERE status = 'published';  -- Partial index
+
+-- Set query timeout for the authenticated role
+ALTER ROLE authenticated SET statement_timeout = '10s';
+```
+
+- [ ] Indexes on all foreign key columns
+- [ ] Indexes on columns used in WHERE, ORDER BY, and JOIN clauses
+- [ ] `pg_stat_statements` enabled for ongoing query monitoring
+- [ ] Performance Advisor reviewed (Dashboard > Database > Performance)
+- [ ] `statement_timeout` set for authenticated role to prevent runaway queries
+- [ ] Table bloat checked — VACUUM if dead tuple percentage > 10%
+
+### Step 13: Apply Migrations with `npx supabase db push`
+
+All schema changes must go through migration files, never manual Dashboard edits in production.
+
 ```bash
-# Pre-flight checks
-curl -f https://staging.example.com/health
-curl -s https://status.supabase.com
+# Generate a migration from local changes
+npx supabase db diff --use-migra -f add_indexes
+
+# Apply migrations to production (linked project)
+npx supabase db push
+
+# Verify migration history
+npx supabase migration list
+
+# If a migration fails, create a rollback
+npx supabase migration new rollback_bad_change
+```
+
+- [ ] All schema changes in `supabase/migrations/` directory (version controlled)
+- [ ] `npx supabase db push` tested against a fresh project
+- [ ] Migration history matches between local and remote (`npx supabase migration list`)
+- [ ] Rollback migration prepared for risky schema changes
+- [ ] No manual schema edits in production Dashboard
 
-# Gradual rollout - start with canary (10%)
-kubectl apply -f k8s/production.yaml
-kubectl set image deployment/supabase-integration app=image:new --record
-kubectl rollout pause deployment/supabase-integration
+### Step 14: Pre-Launch Final Verification
 
-# Monitor canary traffic for 10 minutes
-sleep 600
-# Check error rates and latency before continuing
+```bash
+# Verify RLS status one final time
+npx supabase inspect db table-sizes --linked
 
-# If healthy, continue rollout to 50%
-kubectl rollout resume deployment/supabase-integration
-kubectl rollout pause deployment/supabase-integration
-sleep 300
+# Check that the project is linked to production
+npx supabase status
 
-# Complete rollout to 100%
-kubectl rollout resume deployment/supabase-integration
-kubectl rollout status deployment/supabase-integration
+# Verify connection string works
+npx supabase db ping --linked
 ```
 
+- [ ] CORS settings match production domain (Dashboard > API > CORS)
+- [ ] Environment variables set correctly in deployment platform
+- [ ] Realtime enabled only on tables that need it (reduces connection usage)
+- [ ] Webhook endpoints registered and tested
+- [ ] Load test completed on staging (see `supabase-load-scale`)
+- [ ] SSL enforcement enabled (Dashboard > Database > Settings > SSL)
+- [ ] DNS and custom domain verified end-to-end
+
 ## Output
-- Deployed Supabase integration
-- Health checks passing
-- Monitoring active
-- Rollback procedure documented
+
+- All 14 checklist sections verified with zero unchecked items
+- RLS enforced on every public table with tested policies
+- Key separation verified (anon client-side, service_role server-side only)
+- Connection pooling via Supavisor (port 6543) for all application code
+- Backups, PITR, monitoring, Edge Functions, Storage policies, indexes all verified
+- Migrations applied cleanly via `npx supabase db push`
 
 ## Error Handling
-| Alert | Condition | Severity |
-|-------|-----------|----------|
-| API Down | 5xx errors > 10/min | P1 |
-| High Latency | p99 > 5000ms | P2 |
-| Rate Limited | 429 errors > 5/min | P2 |
-| Auth Failures | 401/403 errors > 0 | P1 |
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `403 Forbidden` on all API calls | RLS enabled but no policies created | Add SELECT/INSERT/UPDATE/DELETE policies for each role |
+| `429 Too Many Requests` | Plan rate limit exceeded | Upgrade plan or implement client-side backoff with retry |
+| Connection timeout under load | Using direct connection in serverless | Switch to pooled connection string (port 6543) |
+| Auth emails not delivered | Default SMTP rate-limited | Configure custom SMTP provider (SendGrid, Resend, Postmark) |
+| `PGRST301` permission denied | Service role key used where anon expected | Check client initialization — use anon key for client-side |
+| Edge Function cold starts | First invocation after idle period | Pre-warm with scheduled pings or accept ~200ms cold start |
+| Storage upload fails | Missing bucket policy or size limit exceeded | Add INSERT policy and check `file_size_limit` on bucket |
+| Slow queries after launch | Missing indexes on filter/join columns | Run Performance Advisor and add indexes per Step 12 |
+| Migration conflicts | Manual Dashboard edits diverged from migration files | Run `npx supabase db diff` to capture drift, then commit |
 
 ## Examples
 
-### Health Check Implementation
+### Client Setup (Next.js)
+
 ```typescript
-async function healthCheck(): Promise<{ status: string; supabase: any }> {
-  const start = Date.now();
-  try {
-    await supabaseClient.ping();
-    return { status: 'healthy', supabase: { connected: true, latencyMs: Date.now() - start } };
-  } catch (error) {
-    return { status: 'degraded', supabase: { connected: false, latencyMs: Date.now() - start } };
-  }
-}
+// lib/supabase/client.ts — browser (anon key)
+import { createClient } from '@supabase/supabase-js';
+export const supabase = createClient<Database>(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+);
+
+// lib/supabase/server.ts — server only (service role)
+export const supabaseAdmin = createClient<Database>(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!,
+  { auth: { autoRefreshToken: false, persistSession: false } }
+);
+```
+
+### RLS Policy Pattern
+
+```sql
+ALTER TABLE public.posts ENABLE ROW LEVEL SECURITY;
+CREATE POLICY "Public read published" ON public.posts
+  FOR SELECT USING (status = 'published');
+CREATE POLICY "Authors manage own" ON public.posts
+  FOR ALL USING (auth.uid() = author_id)
+  WITH CHECK (auth.uid() = author_id);
 ```
 
-### Immediate Rollback
+### Rollback
+
 ```bash
-kubectl rollout undo deployment/supabase-integration
-kubectl rollout status deployment/supabase-integration
+npx supabase migration new rollback_bad_change  # Create reversal SQL
+npx supabase db push                             # Apply rollback
+# For data: Dashboard > Database > Backups > PITR
+# For app: vercel rollback / netlify deploy --prod
 ```
 
+For complete examples including health checks, storage policies, and Edge Functions, see [examples.md](references/examples.md).
+
 ## Resources
-- [Supabase Status](https://status.supabase.com)
-- [Supabase Support](https://supabase.com/docs/support)
+
+- [Going to Production](https://supabase.com/docs/guides/deployment/going-into-prod) — Official production checklist
+- [Maturity Model](https://supabase.com/docs/guides/deployment/maturity-model) — Project lifecycle stages
+- [Shared Responsibility Model](https://supabase.com/docs/guides/deployment/shared-responsibility-model) — What Supabase manages vs. what you manage
+- [Performance Advisor](https://supabase.com/docs/guides/database/inspect) — Built-in query analysis
+- [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler) — Supavisor configuration
+- [RLS Guide](https://supabase.com/docs/guides/database/postgres/row-level-security) — Policy patterns and examples
+- [Edge Functions](https://supabase.com/docs/guides/functions) — Serverless Deno functions
+- [Storage](https://supabase.com/docs/guides/storage) — File storage with policies
+- [`@supabase/supabase-js` Reference](https://supabase.com/docs/reference/javascript/introduction) — Client SDK docs
 
 ## Next Steps
-For version upgrades, see `supabase-upgrade-migration`.
+
+- For SDK version upgrades, see `supabase-upgrade-migration`
+- For load testing before launch, see `supabase-load-scale`
+- For monitoring in production, see `supabase-monitoring`
+- For Edge Function patterns, see `supabase-edge-functions`

package/skills/supabase-prod-checklist/references/errors.md

@@ -0,0 +1,63 @@
+# Error Handling Reference
+
+## Production Error Catalog
+
+| Error | HTTP Status | Cause | Solution |
+|-------|------------|-------|----------|
+| `403 Forbidden` | 403 | RLS enabled but no policies created | Add SELECT/INSERT/UPDATE/DELETE policies for each role |
+| `429 Too Many Requests` | 429 | Plan rate limit exceeded | Upgrade plan or implement client-side exponential backoff |
+| Connection timeout | — | Direct connection in serverless | Switch to pooled connection string (Supavisor port 6543) |
+| `PGRST301` permission denied | 401 | Service role key used where anon expected | Verify client uses anon key for client-side, service_role for server only |
+| Auth emails not delivered | — | Default SMTP rate-limited (4/hour free) | Configure custom SMTP: SendGrid, Resend, or Postmark |
+| Edge Function cold start | — | First invocation after idle period | Pre-warm with scheduled pings or accept ~200ms delay |
+| Storage upload fails | 400/403 | Missing bucket policy or size limit exceeded | Add INSERT policy on `storage.objects` and check `file_size_limit` |
+| Slow queries | — | Missing indexes on filter/join columns | Run Performance Advisor, add indexes per foreign keys and WHERE clauses |
+| Migration conflicts | — | Manual Dashboard edits diverged from files | Run `npx supabase db diff` to capture drift, commit as migration |
+| Realtime disconnects | — | Concurrent connection limit exceeded per tier | Reduce subscriptions or upgrade plan tier |
+
+## Alert Thresholds
+
+| Alert | Condition | Severity | Action |
+|-------|-----------|----------|--------|
+| API Down | 5xx errors > 10/min | P1 — Critical | Check Supabase status page, verify Edge Functions, check DB connections |
+| High Latency | p99 > 5000ms | P2 — Warning | Run Performance Advisor, check missing indexes, verify connection pooling |
+| Rate Limited | 429 errors > 5/min | P2 — Warning | Implement backoff, consider plan upgrade, audit request patterns |
+| Auth Failures | 401/403 errors spike | P1 — Critical | Check RLS policies, verify JWT expiry, audit auth provider settings |
+| Pool Exhaustion | Active connections > 80% pool | P1 — Critical | Switch to Supavisor pooled connection, reduce direct connections |
+| Storage Quota | Usage > 80% of plan limit | P3 — Info | Clean unused files, upgrade plan, implement lifecycle policies |
+
+## Supabase Error Code Reference
+
+```typescript
+// Common Supabase error shapes
+interface SupabaseError {
+  message: string;
+  details: string | null;
+  hint: string | null;
+  code: string;  // PostgreSQL error code
+}
+
+// Handle errors in application code
+const { data, error } = await supabase.from('posts').select('*');
+if (error) {
+  switch (error.code) {
+    case '42501': // insufficient_privilege — RLS blocking
+      console.error('RLS policy missing or too restrictive');
+      break;
+    case '23505': // unique_violation
+      console.error('Duplicate record:', error.details);
+      break;
+    case '23503': // foreign_key_violation
+      console.error('Referenced record does not exist');
+      break;
+    case '57014': // statement_timeout
+      console.error('Query timed out — add index or optimize');
+      break;
+    default:
+      console.error('Supabase error:', error.message);
+  }
+}
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*