Supabase Advanced Troubleshooting

Overview

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.

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.

Prerequisites

• 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

Authentication

Every technique here runs against your own project's Postgres, so authenticate with project-scoped credentials, never a shared key:

• psql / SQL Editor — connect with the project's direct connection string or pooled Supavisor URI from Dashboard → Settings → Database. Keep the database password in an env var (PGPASSWORD / .pgpass), never inline in a command.
• SDK (createClient) — pass the service-role key (SUPABASE_SERVICE_ROLE_KEY) for the diagnostic RPCs below, since they read pg_stat_activity and system catalogs that the anon key cannot. Load it from the environment; never commit it.
• supabase CLI — run supabase login once (stores a personal access token), then supabase link --project-ref <ref> for Edge Function logs.

Instructions

Work the three diagnostic tracks in the order the symptom points to. Each track's full query set and SDK helper lives in a reference file — SKILL.md carries the skeleton so you can start immediately, then drill in for the complete toolkit.

Step 1: pg_stat_statements and slow query analysis

Enable pg_stat_statements, then rank queries by total execution time, call frequency, and cache-hit ratio to find the real cost centers. Follow up with EXPLAIN (ANALYZE, BUFFERS) on the worst offenders and add targeted indexes with CREATE INDEX CONCURRENTLY. The starter query:

CREATE EXTEN…

Supabase Architecture Variants

Overview

Every Supabase createClient configuration turns on two questions: where the client runs (browser vs server) and which key it uses (anon respects RLS; service_role bypasses it). This skill supplies production-ready patterns for five architectures — Next.js SSR, SPA, Mobile, Serverless Edge Functions, and Multi-tenant isolation.

Prerequisites

• @supabase/supabase-js v2+ installed
• @supabase/ssr package for Next.js SSR (v0.5+)
• Supabase project with URL, anon key, and service_role key
• TypeScript project with generated database types (supabase gen types typescript)
• For mobile: React Native with Expo or bare workflow

Instructions

Pick the architecture that matches the target stack, then follow the linked walkthrough for the full, copy-ready client setup.

Step 1 — Next.js SSR (App Router)

Next.js App Router needs two separate clients: a server client that reads/writes auth cookies via @supabase/ssr, and a browser client for client components. A third service_role admin client is used only in Server Actions/Route Handlers and must never reach the browser. The browser client is the minimal skeleton:

// lib/supabase/client.ts
'use client'
import { createBrowserClient } from '@supabase/ssr'
import type { Database } from '../database.types'

export function createSupabaseBrowser() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!  // anon key only — respects RLS
  )
}

Full walkthrough — server client, admin client, middleware session refresh, server component usage, Server Actions, and the OAuth callback route: …

Supabase Auth + Storage + Realtime Core

Overview

Implement the three pillars that turn a Supabase database into a full application backend: user authentication (email/password, OAuth, magic links, session lifecycle), file storage (uploads, downloads, signed URLs, bucket-level RLS policies), and real-time subscriptions (Postgres change events, client-to-client broadcast, presence tracking). Every operation integrates with Row-Level Security through auth.uid().

Each pillar below carries a lean skeleton in this file; the full, copy-paste walkthroughs live in references/ so this file stays scannable.

Prerequisites

• Supabase project created at supabase.com/dashboard
• @supabase/supabase-js v2 installed (npm install @supabase/supabase-js)
• SUPABASE_URL and SUPABASE_ANON_KEY available from project Settings > API
• For Python: pip install supabase (wraps postgrest-py, gotrue-py, storage3, realtime-py)

Instructions

Read the file (Read), edit or create the client and route/component code (Write, Edit), and grep the project (Grep) to reuse an existing Supabase client before creating a new one. Use Bash(npm:*) to install the SDK and Bash(supabase:*) to run migrations/policies.

Step 1: Auth — registration, login, OAuth

Initialize the client once, then wire the flows your app needs. The skeleton:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)

// Email/password
await supabase.auth.signUp({ email, password })
await supabase.auth.signInWithPassword({ email, password })

// OAuth — redirect the user to data.url
const { data } = await supabase.auth.signInWithOAuth({ provider: 'google' })

// React to session changes (SIGNED_IN / SIGNED_OUT / TOKEN_REFRESHED)
supabase.auth.onAuthStateChange((event, session) => { /* update UI */ })

Full auth walkthrough — OAuth callback, magic link, session lifecycle, password reset: references/auth.md. Python: references/python-examples.md.

Step 2: Storage — upload, download, secure with bucket policies

Public buckets serve via CDN URLs; private buckets require signed URLs. The skeleton:

// Upload to the signe…

Supabase CI Integration

Overview

Build GitHub Actions workflows that automate the full Supabase lifecycle: link projects in CI, push migrations on merge, deploy Edge Functions, generate TypeScript types, run tests against a local Supabase instance, and create preview branches for pull requests. Every database change gets validated before it reaches production.

The pull-request CI pipeline runs these stages, all detailed in ci-workflows.md:

1. Start a local Supabase instance (unused services disabled for speed).
2. Apply every migration from scratch with npx supabase db reset.
3. Regenerate TypeScript types and fail the build on drift from the committed version.
4. Run pgTAP database tests and the application test suite against the local instance.
5. Stop Supabase (always, even on failure).

Prerequisites

• GitHub repository with Actions enabled
• Supabase project created at supabase.com/dashboard
• Supabase CLI initialized locally (npx supabase init)
• Node.js 18+ in your project
• @supabase/supabase-js installed:

npm install @supabase/supabase-js

Instructions

Step 1: Configure GitHub Secrets and Link in CI

Store credentials as GitHub repository secrets. The CI pipeline uses these to authenticate with your Supabase project without exposing tokens in code.

# Set secrets via GitHub CLI
gh secret set SUPABASE_ACCESS_TOKEN --body "<your-access-token>"
gh secret set SUPABASE_DB_PASSWORD --body "<your-database-password>"
gh secret set SUPABASE_PROJECT_REF --body "<your-project-ref>"

Generate your access token at supabase.com/dashboard/account/tokens. Find your project ref in Project Settings > General.

Link the project in any CI job that needs remote access:

- name: Install Supabase CLI
  uses: supabase/setup-cli@v1
  with:
    version: latest

- name: Link Supabase project
  run: npx supabase link --project-ref ${{ secrets.SUPABASE_PROJECT_REF }}
  env:
    SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}

Step 2: CI Workflow — Test, Validate Migrations, and Generate Types

Add .github/workflows/supabase-ci.yml that runs on every pull request. It starts a local Supabase instance, runs db reset to apply all migrations from scratch, regenerates types and fails on drift (git diff --exit-code), then runs pgTAP and application tests. The …

Supabase Common Errors

Overview

Diagnostic guide for Supabase errors across PostgREST (PGRST*), PostgreSQL (numeric codes), Auth, Storage, and Realtime. Identify the error layer, trace the root cause, and apply the correct fix — every SDK call returns { data, error } where data is null when error exists.

The workflow is three steps: capture the error object, classify it by layer and code, then apply and verify the fix. Full step-by-step code lives in the diagnostic walkthrough; complete lookup tables are in the error reference.

Prerequisites

• @supabase/supabase-js installed (npm install @supabase/supabase-js)
• SUPABASE_URL and SUPABASE_ANON_KEY (or SUPABASE_SERVICE_ROLE_KEY) configured
• Access to Supabase Dashboard (for log inspection and SQL Editor)
• Supabase CLI installed for local development (npx supabase --version)

Instructions

Step 1 — Capture the Error Object

Every Supabase SDK call returns a { data, error } tuple. Never assume data exists — always destructure and check error first, because data is null whenever error is set.

const { data, error } = await supabase.from('todos').select('*')
if (error) {
  console.error(`[${error.code}] ${error.message}`)
  return  // data is null here — do not touch it
}
console.log(`Found ${data.length} rows`)

If error is undefined rather than null, upgrade to @supabase/supabase-js@2.x. See the walkthrough for the full guard pattern.

Step 2 — Identify the Error Layer and Code

Match the code prefix to its subsystem, then look it up in the Error Handling tables below:

• PGRST* → PostgREST (API gateway: JWT, query parsing, schema)
• 5-digit numeric (e.g. 42501, 23505) → PostgreSQL engine (RLS, constraints, migrations)
• AuthApiError → Auth service (credentials, confirmation, token expiry)
• StorageApiError → Storage service (bucket, RLS on storage.objects, size limits)

A missing code u…

Supabase Cost Tuning

Overview

Reduce Supabase spend by auditing usage against plan limits, eliminating database and storage waste, and right-sizing compute resources. The three biggest levers: database optimization (vacuum, index cleanup, archival), storage lifecycle management (compress before upload, orphan cleanup), and connection pooling to reduce compute add-on requirements.

Work the three steps below in order — audit first to find where the money goes, then optimize the biggest offenders, then right-size compute. Each step keeps a representative snippet inline; the full query and script sets live in references/ so this file stays scannable.

Prerequisites

• Supabase project with Dashboard access (Settings > Billing)
• @supabase/supabase-js installed: npm install @supabase/supabase-js
• Service role key for admin operations (storage audit, cleanup scripts)
• SQL editor access (Dashboard > SQL Editor or psql connection)

Pricing Reference

Compute add-ons (Pro and above):

Decision framework: Read replicas ($25/mo each) beat scaling up when reads dominate and geographic distribution is needed. Connection pooling (Supavisor, free) reduces compute pressure from idle connections.

Instructions

Step 1: Audit current usage and identify cost drivers

Find where the database budget is going before changing anything. Run the audit queries in the SQL Editor to surface the biggest tables, unused indexes, dead-tuple bloat, and connection count. Start with total…

Supabase Data Handling

Overview

GDPR and CCPA compliance with Supabase uses a layered approach: Row Level Security (RLS) for tenant data isolation, supabase.auth.admin.deleteUser() for right-to-deletion, SQL-based exports for subject access requests, PII detection across columns, automated retention with pg_cron, and point-in-time recovery for backup/restore. Every requirement maps to a real Supabase SDK method or PostgreSQL feature.

When to use: Implement GDPR right-to-deletion, respond to data subject access requests (DSARs), audit PII in the database, configure automated retention, set up tenant isolation with RLS, or plan backup/restore procedures.

Prerequisites

• @supabase/supabase-js v2+ with service role key for admin operations
• Supabase project on Pro plan (for pg_cron and point-in-time recovery)
• Understanding of GDPR Articles 15-17 (access, rectification, erasure)
• Database access via SQL Editor or psql for schema changes

Instructions

Step 1: RLS for Data Isolation and PII Column Management

Enable RLS on every table holding user data, then classify PII columns so later deletion and export steps know what to touch. The RLS skeleton is one USING (auth.uid() = ...) policy per access pattern:

ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;

CREATE POLICY "users_read_own_profile" ON public.profiles
  FOR SELECT USING (auth.uid() = id);

Pair the policies with a PII audit — an information_schema.columns scan by naming pattern, COMMENT ON COLUMN tags, a pii_registry view, and an SDK-side regex scanner for emails, phones, SSNs, and IPs.

See RLS and PII reference for the full multi-tenant policy set, the PII audit SQL, the pii_registry view, and the scanTableForPII() SDK scanner.

Step 2: User Deletion and Data Export

Implement GDPR Article 17 (erasure) and Article 15 (access). Deletion runs in cascade order — application tables, then storage files, then the auth user, then an immutable audit-log entry that must survive the erasure:

// Cascade order matters: children before parents, auth user last
const tablesToPurge = ['comments', 'orders', 'documents', 'profiles'];
// ...delete rows, remove storage files, then:
await supabase.auth.admin.deleteUser(userId);
await supabase.from('gdpr_audit_log').insert({ action: 'USER_DELETION', subject_id: userId });

Export is the inverse: read every user-scoped table plus storage listin…

Supabase Debug Bundle

Overview

Collect a comprehensive, redacted diagnostic bundle from a Supabase project. Tests connectivity, auth, Realtime, Storage, RLS policy behavior, and database health — then packages everything into a single archive safe for sharing with Supabase support.

Current State

!node --version 2>/dev/null || echo 'Node.js not found' !npx supabase --version 2>/dev/null || echo 'Supabase CLI not found' !npm list @supabase/supabase-js 2>/dev/null | grep supabase || echo '@supabase/supabase-js not installed'

Prerequisites

• Node.js 18+ with @supabase/supabase-js v2 installed in the project
• Supabase CLI installed (npm i -g supabase or npx supabase)
• Environment variables set: SUPABASE_URL and SUPABASE_ANON_KEY (minimum); SUPABASE_SERVICE_ROLE_KEY for full diagnostics
• Project linked via supabase link --project-ref <ref> (for CLI commands)

Instructions

Step 1: Gather Environment and Connectivity

Collect SDK version, project URL, key type, and test basic connectivity against the REST and Auth endpoints.

import { createClient } from '@supabase/supabase-js'

const url = process.env.SUPABASE_URL!
const anonKey = process.env.SUPABASE_ANON_KEY!
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY

// Identify which key is in use
const keyType = serviceKey ? 'service_role' : 'anon'
const supabase = createClient(url, serviceKey ?? anonKey, {
  auth: { autoRefreshToken: false, persistSession: false }
})

const diagnostics: Record<string, unknown> = {}

// 1a — SDK + environment
diagnostics.environment = {
  supabase_js_version: require('@supabase/supabase-js/package.json').version,
  node_version: process.version,
  project_url: url.replace(/https:\/\/([^.]+)\..*/, 'https://$1.***'),
  key_type: keyType,
  timestamp: new Date().toISOString(),
}

// 1b — REST API connectivity
const restStart = Date.now()
const restRes = await fetch(`${url}/rest/v1/`, {
  headers: { apikey: anonKey, Authorization: `Bearer ${anonKey}` },
})
diagnostics.rest_api = {
  status: restRes.status,
  latency_ms: Date.now() - restStart,
  ok: restRes.ok,
}

// 1c — Auth health
const authStart = Date.now()
const { data: sessionData, error: sessionErr } = await supabase.auth.getSession()
diagnostics.auth = {
  status: sessionErr ? `error: ${sessionErr.message}` : 'ok',
  has_session: !!sessionData?.session,
  latency_ms: Date.now() - authStart,
}

// 1d — Database connectivity probe
const dbStart = Date.now()
const { error: dbErr } = await supabase.from('_test_ping').select('*').limit(1)
diagnostics.database = {
  // 42P0…

Supabase Deploy Integration

Overview

Deploy and manage Supabase projects in production with confidence. This skill covers the full deployment lifecycle: pushing database migrations, deploying Edge Functions, managing secrets, executing zero-downtime rollouts with blue/green database branching, rolling back failed migrations, and verifying deployment health. All commands use the Supabase CLI with --project-ref for explicit project targeting.

SDK: @supabase/supabase-js — supabase.com/docs

Prerequisites

• Supabase CLI installed (npm install -g supabase or npx supabase)
• Supabase project linked (npx supabase link --project-ref <your-ref>)
• Database migrations in supabase/migrations/ directory
• Edge Functions in supabase/functions/ directory (if deploying functions)
• SUPABASE_ACCESS_TOKEN set for CI/non-interactive environments

Instructions

Step 1 — Push Database Migrations and Deploy Edge Functions

Apply pending database migrations to your production project, then deploy Edge Functions with their required secrets.

Database migrations:

# Apply all pending migrations to production
npx supabase db push --project-ref $PROJECT_REF

# Preview what will run without applying (dry run)
npx supabase db push --project-ref $PROJECT_REF --dry-run

# Check current migration status
npx supabase migration list --project-ref $PROJECT_REF

Each migration file in supabase/migrations/ is applied in timestamp order. The CLI tracks which migrations have already been applied and only runs new ones.

Edge Functions deployment:

# Deploy a single Edge Function
npx supabase functions deploy process-webhook --project-ref $PROJECT_REF

# Deploy all Edge Functions at once
npx supabase functions deploy --project-ref $PROJECT_REF

Secrets management — set environment variables for Edge Functions:

# Set individual secrets
npx supabase secrets set STRIPE_KEY=sk_live_xxx --project-ref $PROJECT_REF
npx supabase secrets set WEBHOOK_SECRET=whsec_xxx --project-ref $PROJECT_REF

# Set multiple secrets at once
npx supabase secrets set API_KEY=value1 SIGNING_KEY=value2 --project-ref $PROJECT_REF

# List current secrets (names only, values hidden)
npx supabase secrets list --project-ref $PROJECT_REF

# Remove a secret
npx supabase secrets unset OLD_KEY --project-ref $PROJECT_REF

Step 2 — Zero-Downtime Deployments and Blue/Green Branching

Use Supabase database branching to test migrations against a production-like environment before cutting over.

Blue/green depl…

Supabase Enterprise RBAC

Overview

Supabase supports custom role-based access control (RBAC) by storing role information in app_metadata on the user's JWT, then reading those claims in RLS policies via auth.jwt() ->> 'role'. This skill implements a complete RBAC system: roles in app_metadata, RLS policies that enforce role hierarchies, organization-scoped access, role management through the Admin API, and API endpoints protected with role checks — all using real createClient from @supabase/supabase-js.

When to use: Building multi-role applications (admin/editor/viewer), implementing organization-scoped access, creating custom permission systems beyond Supabase's built-in anon/authenticated roles, or scoping API operations by user role.

Prerequisites

• @supabase/supabase-js v2+ with service role key for admin operations
• Understanding of JWT claims and Supabase's auth.jwt() SQL function
• Database access via SQL Editor or psql for RLS policy creation
• Supabase project with authentication configured

Instructions

The workflow has three steps: assign roles into the JWT, enforce them in the database with RLS, then enforce them again in application code.

Step 1: Define Roles via app_metadata and JWT Claims

Store custom roles in the user's app_metadata using the Admin API. These claims appear in every JWT the user receives and are readable in RLS policies. Assign roles with the service-role client:

// Define the role hierarchy
type AppRole = 'admin' | 'editor' | 'viewer' | 'member';

// Assign a role to a user (admin operation, service role key required)
async function setUserRole(userId: string, role: AppRole, orgId: string) {
  const { data, error } = await supabase.auth.admin.updateUserById(userId, {
    app_metadata: { role, org_id: orgId },
  });
  if (error) throw new Error(`Failed to set role: ${error.message}`);
  return data.user;
}

Read the role back in app code with supabase.auth.getUser() and compare it against a numeric hierarchy so hasRole('editor', 'viewer') is true. See role assignment and JWT extraction for the full service-role client setup, granular permissions, bulk assignTeamRoles(), getCurrentUserRole(), getCurrentOrg(), hasRole(), and the requireRole() guard.

Step 2: RLS Policies with JWT Role Claims

Write Row Level Security policies that read …

Supabase Hello World — First Query

Overview

Execute your first real Supabase query: create a todos table in the dashboard, insert a row with the JS client, and read it back. This validates that your project URL, anon key, and Row Level Security are configured correctly before you build anything else.

Prerequisites

• Completed supabase-install-auth setup (project URL + anon key in .env)
• @supabase/supabase-js v2+ installed (npm install @supabase/supabase-js)
• A Supabase project at supabase.com/dashboard

Instructions

The workflow is three steps: create the table (dashboard SQL), insert a row with the JS client, and read it back to prove the round-trip. The skeleton below is enough to follow along; the fully annotated code for every step — including the error-branch comments and expected console output — lives in the full implementation walkthrough.

Step 1: Create the todos Table

In the Supabase dashboard SQL Editor, create the table, enable Row Level Security (required for anon-key access), and add permissive read + insert policies for the hello-world exercise:

create table public.todos (
  id bigint generated always as identity primary key,
  task text not null,
  is_complete boolean default false,
  inserted_at timestamptz default now()
);

alter table public.todos enable row level security;

create policy "Allow public read" on public.todos
  for select using (true);

create policy "Allow public insert" on public.todos
  for insert with check (true);

Lock these policies down before production. Verify the table appears under Table Editor before continuing.

Step 2: Insert a Row

Create the client from your env vars, then insert. Chain .select() to get the inserted row back — .insert() alone returns { data: null }:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
)

const { data, error } = await supabase
  .from('todos')
  .insert({ task: 'Hello from Supabase!' })
  .select()

Step 3: Read It Back

Select all rows and confirm the row you inserted is present:

const { data: todos } = await supabase.from('todos').select('*')
// [{ id: 1, task: "Hello from Supabase!", is_complete: false, ... }]

Open the Table Editor in the dash…

Supabase Incident Runbook

Overview

A structured response for Supabase-backed application failures. Work three layers in order: triage platform vs. application, run pg_stat_activity database diagnostics, then debug RLS, Edge Functions, and storage — ending with an evidence bundle for support escalation.

When to use: Production errors involving Supabase, degraded API response times, connection pool exhaustion, silent data filtering from RLS, Edge Function cold start failures, or storage upload/download errors.

Each step below gives the workflow plus a first command. The complete copy-paste blocks for every step live in references/diagnostics.md.

Prerequisites

• Supabase project with dashboard access at supabase.com/dashboard
• @supabase/supabase-js v2+ installed in your project
• Supabase CLI installed for Edge Function log access
• Direct database connection string (for psql diagnostics)
• Access to status.supabase.com for platform health

Instructions

Step 1: Triage — Platform vs. Application

Determine whether the issue is a Supabase platform incident or an application-level bug. Check the official status page first, then verify SDK client connectivity. Use Read to inspect the app's Supabase env config and Grep to scan application logs for HTTP error codes (401=auth, 429=rate limit, 500=server).

# Check official status page — is this a platform-wide incident?
curl -sf https://status.supabase.com/api/v2/status.json | jq '.status'
# Expected: { "indicator": "none", "description": "All Systems Operational" }

If the status page is green, run the SDK healthCheck() (a select 1 against a small _health_check table) to measure latency and confirm connectivity. A green platform plus a failing health check points at your queries, RLS, or Edge Functions — the SDK block, incident-check query, and full decision tree are in references/diagnostics.md.

Step 2: Database Diagnostics with pg_stat_activity

Connect directly via psql (or the Supabase SQL Editor) to inspect connections, find stuck queries, and detect leaks.

-- Current connections grouped by state — the first thing to run
SELECT state, count(*) AS connections,
     …

Supabase Install & Auth

Overview

Install the Supabase SDK, CLI, and project credentials from scratch — covering package install, environment configuration, client initialization, and connection verification for both TypeScript (@supabase/supabase-js) and Python (supabase).

Key facts:

• npm package: @supabase/supabase-js
• Python package: supabase (via pip)
• Client factory: createClient() — never new SupabaseClient()
• Dashboard: https://supabase.com/dashboard (Settings > API for keys)
• Docs: https://supabase.com/docs

Prerequisites

• Node.js 18+ (for JS/TS) or Python 3.8+ (for Python)
• Package manager: npm, pnpm, or yarn (JS) / pip (Python)
• A Supabase project created at https://supabase.com/dashboard
• Docker Desktop (only if using local development via supabase start)

Instructions

Step 1 — Install the SDK and CLI

Install the SDK and the Supabase CLI:

JavaScript / TypeScript:

# Install the SDK
npm install @supabase/supabase-js

# For SSR frameworks (Next.js, SvelteKit, Nuxt), also install:
npm install @supabase/ssr

# Install the Supabase CLI (for types, migrations, local dev)
npm install -D supabase

Python:

# Install the SDK
pip install supabase

# Install the CLI (alternative: brew install supabase/tap/supabase)
npm install -g supabase

Verify the CLI is available:

npx supabase --version

Step 2 — Configure Environment Variables

Retrieve project credentials from the Supabase Dashboard (Settings > API) and create the env file:

# .env.local (or .env)
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...          # anon key — safe for client-side
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1...  # admin key — server-side ONLY

Add env files to .gitignore immediately:

.env
.env.local
.env.*.local

Security rules:

• The anon key (SUPABASE_KEY) is safe for client-side code. It respects Row Level Security (RLS) policies.
• The service role key (SUPABASE_SERVICE_ROLE_KEY) bypasses RLS entirely. Use only on the server. Never bundle into client code or expose in browser.

Step 3 — Initialize the Client and Verify

Create a client singleton and verify connectivity:

TypeScript — client-side (anon key):

…

Supabase Known Pitfalls

Overview

The twelve most common Supabase mistakes, ranked by severity: security (service_role exposure, missing RLS, permissive policies, no connection pooling), data integrity (ignoring { data, error }, missing .select() after mutations, .single() on optional results), and performance / maintainability (select('*'), N+1 queries, missing FK indexes, multiple client instances, no generated types). Each pitfall shows the broken code, why it fails, and the correct pattern using createClient from @supabase/supabase-js.

This SKILL.md carries the full pitfall table plus one representative fix per category. The verbatim broken-vs-correct code and detection queries for all twelve live in references/pitfalls.md — drill in there for depth.

Prerequisites

• Access to a Supabase project codebase for review
• @supabase/supabase-js v2+ installed
• Basic understanding of Row Level Security (RLS)

Instructions

Work the pitfalls top-down by severity. Fix every Critical finding before moving on — a single security miss can expose the whole database.

Supabase Load & Scale

Overview

Supabase scaling operates at six layers: read replicas (offload analytics and reporting queries), connection pooling (Supavisor, the 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 gives the high-level workflow inline and links to references/ for the full createClient config, SQL, and CLI for each layer.

Prerequisites

• 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

Instructions

Step 1 — Read Replicas and Connection Pooling

Route read-heavy queries (dashboards, reports, search) to a read replica while keeping writes on the primary. Supavisor pools connections in two modes: transaction (default, port 6543 — shares connections, no prepared statements) and session (port 5432 — one connection per client, needed for prepared statements and LISTEN/NOTIFY). Configure two clients — a primary and a read-only replica pointed at the -ro URL:

// lib/supabase.ts
export const supabase = createClient<Database>(
  process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)       // writes + realtime
export const supabaseReadOnly = createClient<Database>(
  process.env.SUPABASE_READ_REPLICA_URL!, process.env.SUPABASE_ANON_KEY!) // analytics

Then send analytics queries to supabaseReadOnly and all writes to supabase. Replicas lag slightly (typically <100ms), so never read-after-write on a replica. Full client config, pooled psql connection strings, query-routing services, and a pool-usage monitoring query: read replicas and connection pooling.

Step 2 — Compute Upgrades, CDN for Storage, and Edge Function Regions

Match compute tier to traffic (Micro 60 connections → 4XL 480), serve public Storage buckets through the CDN with long cacheControl headers plus content-addressed paths for cache busting, and deploy Edge Functions to the region closest to users:

supabase projects update --experimenta…

Supabase Local Dev Loop

Overview

Run the full Supabase stack locally — Postgres, Auth, Storage, Realtime, Edge Functions, and Studio — using Docker and the Supabase CLI. Local development mirrors production APIs exactly, enabling offline work, fast iteration, and repeatable migration workflows. Schema changes flow through supabase db diff to generate migrations, and supabase db reset replays them cleanly.

Prerequisites

• Docker Desktop installed and running (required for all local services)
• Node.js 18+ (for npx supabase commands)
• No global install needed — all commands use npx supabase

Instructions

Step 1: Initialize Project and Start Local Stack

# Initialize Supabase in your project root
npx supabase init

This creates a supabase/ directory:

supabase/
├── config.toml          # Local stack configuration (ports, auth settings)
├── migrations/          # SQL migration files (version-controlled)
└── seed.sql             # Seed data (runs after migrations on db reset)

Start the local stack (first run pulls Docker images — takes a few minutes):

npx supabase start

The CLI prints all local endpoints and keys:

API URL:          http://localhost:54321
GraphQL URL:      http://localhost:54321/graphql/v1
S3 Storage URL:   http://localhost:54321/storage/v1/s3
DB URL:           postgresql://postgres:postgres@localhost:54322/postgres
Studio URL:       http://localhost:54323
Inbucket URL:     http://localhost:54324
anon key:         eyJhbGciOiJI...
service_role key: eyJhbGciOiJI...

Create .env.local from these values (git-ignored):

# .env.local
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<anon-key-from-supabase-start>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key-from-supabase-start>
DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

Verify the stack is running:

npx supabase status

Step 2: Create Migrations and Seed Data

Create a migration file with a descriptive name:

npx supabase migration new create_profiles
# Creates: supabase/migrations/<timestamp>_create_profiles.sql

Write the migration SQL:

-- supabase/migrations/<timestamp>_create_profiles.sql
create table public.profiles (
  id uuid references auth.users(id) primary key,
  username text unique not null,
  avatar_url text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- Always enable RLS on public tables
alter table public.profiles enable row level security;

create policy "Public profiles…

Supabase Migration Deep Dive

Overview

Supabase migrations are timestamped SQL files managed by the CLI that track schema changes across environments. This skill covers the full lifecycle — creating migrations, zero-downtime schema changes, batch backfills, versioning, rollback, and TypeScript type generation — using real CLI commands and createClient from @supabase/supabase-js.

When to use: Creating new database migrations, modifying production schemas without downtime, backfilling existing data after adding columns, managing migration history across dev/staging/production, rolling back failed migrations, or regenerating TypeScript types.

Prerequisites

• Supabase CLI installed: npm install -g supabase or npx supabase --version
• @supabase/supabase-js v2+ installed in your project
• Local Supabase running: npx supabase start
• Understanding of PostgreSQL DDL and transaction behavior

Instructions

Step 1: Create and Manage Migrations

Create each migration as a timestamped SQL file, write the DDL, test it against a local reset, then promote it through environments with db push:

npx supabase migration new add_profiles_table   # create timestamped SQL file
npx supabase migration list                      # show applied/pending status
npx supabase db reset                            # apply + seed locally (destructive)
npx supabase gen types typescript --local > lib/database.types.ts
npx supabase link --project-ref "<ref>" && npx supabase db push   # promote to remote

Write DDL that enables RLS, adds policies, indexes, and triggers in the same file so the schema is complete when applied. For the full worked migration (a profiles table with RLS policies, an email index, a signup trigger, and an updated_at trigger) plus the local-test and staging/production promotion commands, see creating migrations.

Step 2: Zero-Downtime Migration Patterns

Production schema changes must avoid locking tables. The core rules: adding a nullable column with a default is lock-free on Postgres 11+; build indexes with CREATE INDEX CONCURRENTLY in a -- supabase:disable-transaction migration; rename or retype a column in two phases (add new column, backfill, sync trigger, then drop the old one) rather than an in-place ALTER COLUMN. Example of the safe column-add:

-- Nullable column with a default does NOT lock the table in Postgres 11+
ALTER TABLE public.orders ADD COLUMN status text DEFA…

Supabase Multi-Environment Setup

Overview

Production Supabase deployments require a separate project per environment — each with its own URL, API keys, database, and RLS policies. This skill configures a three-tier architecture (local dev, staging, production) with safe migration promotion via supabase db push, environment-aware createClient initialization, database branching for preview deployments, and CI/CD that prevents accidental cross-environment operations.

When to use: setting up a new project with multiple environments, migrating from a single-project setup, adding staging to an existing dev/prod split, or configuring preview environments with database branching.

Prerequisites

• Three separate Supabase projects created at supabase.com/dashboard (dev, staging, production)
• Supabase CLI installed: npm install -g supabase or npx supabase --version
• @supabase/supabase-js v2+ installed in your project
• Node.js 18+ with a framework that supports .env files (Next.js, Nuxt, SvelteKit, etc.)
• A secret management solution for CI (GitHub Actions Secrets, Vercel env vars, etc.)

Instructions

The workflow is three steps. Each step below gives the shape and the one command that matters; the full implementation walkthrough carries the complete env files, TypeScript client factory, RLS policies, CI/CD workflow, and seed data verbatim.

Step 1: Environment Files and Project Layout

Keep one Supabase CLI project with shared migrations and one .env.* file per environment. Each file points at a different Supabase project; only .env.local is safe to commit.

supabase/migrations/   # shared schema — every env applies the same migrations
.env.local             # supabase start defaults (safe to commit)
.env.staging           # staging project creds  (gitignored)
.env.production        # production project creds (gitignored — NEVER commit)

The CLI links one project at a time. Before any db push or functions deploy, re-link to the target:

npx supabase link --project-ref <target-ref>

See the implementation walkthrough (Step 1) for full .env.* contents, the .gitignore block, and the local-port reference.

Step 2: Environment-Aware Client and Safeguard…

Supabase Observability

Overview

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.

Follow the three steps below from this file for the high-level workflow, then drill into the linked references/ files for the full commands, SQL, and function source.

Prerequisites

• 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

Instructions

Step 1: Dashboard Reports and CLI Inspect Commands

Start with the built-in Dashboard > Reports (API Requests, Database, Auth Usage, Storage, Realtime) for high-level metrics. For deeper Postgres diagnostics, use the supabase inspect db subcommands — begin with cache hit ratio and sequential scans:

# Cache hit ratio — should be > 99% (below 95% means upgrade compute)
npx supabase inspect db cache-hit --linked

# Sequential scans — tables needing indexes
npx supabase inspect db seq-scans --linked

The full report table plus all nine inspect subcommands (table sizes, index usage, long-running queries, bloat, blocking, replication slots, and more) are in references/cli-inspect-commands.md.

Step 2: Query Analytics with pg_stat_statements and Log Drains

Enable pg_stat_statements for query-level metrics, then rank queries by execution time:

create extension if not exists pg_stat_statements;

-- Top slowest queries by average execution time
select substring(query, 1, 80) as query_preview, calls,
  round(mean_exec_time::numeric, 2) as avg_ms
from pg_stat_statements
where mean_exec_time > 50
order by mean_exec_time desc limit 20;

Forward logs to external aggregation with a log drain:

npx supabase log-drains add --name datadog-drain --type datadog \
  --datadog-api-key "$DATADOG_API_KEY" --datadog-region us1 --linked

The complete slow-query / high-frequency / connection-monitoring SQL set and every log-drain command (Datadog, webhook, list, remove) are in …

Supabase Performance Tuning

Overview

Systematically improve Supabase query and database performance across three layers: PostgreSQL engine (indexes, query plans, materialized views), Supabase infrastructure (Supavisor connection pooling, Edge Functions, read replicas), and client SDK patterns (column selection, pagination, RPC functions). Every technique here is measurable — run EXPLAIN ANALYZE before and after to confirm the improvement.

Prerequisites

• Supabase project (local or hosted) with @supabase/supabase-js v2+ installed
• Supabase CLI installed (npx supabase --version to verify)
• Access to the SQL Editor in the Supabase Dashboard or a direct Postgres connection
• pg_stat_statements extension enabled (Step 1 covers this)

Instructions

Step 1: Diagnose — Find What Is Slow

Start every performance effort with data. Enable pg_stat_statements and run the Supabase CLI diagnostics to identify bottlenecks before optimizing.

Enable the stats extension:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Find the slowest queries by average execution time:

SELECT
  query,
  calls,
  mean_exec_time::numeric(10,2) AS avg_ms,
  total_exec_time::numeric(10,2) AS total_ms,
  rows
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 10;

Check index usage and cache hit rates with the Supabase CLI:

# Which indexes are actually being used?
npx supabase inspect db index-usage

# What percentage of queries are served from cache vs disk?
npx supabase inspect db cache-hit

# Tables consuming the most space
npx supabase inspect db table-sizes

Inspect active connections for pooling issues:

SELECT state, count(*), max(age(now(), state_change)) AS max_age
FROM pg_stat_activity
WHERE datname = current_database()
GROUP BY state;

If idle connections exceed your plan's limit or active queries show high max_age, connection pooling (Step 2) and query optimization (Step 3) are the priority.

Step 2: Indexes and Query Plans

Indexes are the single highest-impact optimization. Use EXPLAIN ANALYZE to read query plans, then create targeted indexes.

Read a query plan:

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM users WHERE email = 'alice@example.com';

Look for Seq Scan on large tables — that means no index is being used. After adding an index, the plan should show Index Scan or Index Only Scan.

Create a basic index:

Supabase Policy Guardrails

Overview

Organizational governance for Supabase at scale: a shared RLS policy library (reusable templates for common access patterns), naming conventions (tables, columns, functions, policies), migration review process (CI checks ensuring RLS, preventing destructive operations, enforcing naming), cost alert configuration (billing thresholds and usage monitoring), and security audit scripts (scanning for exposed keys, missing RLS, overly permissive policies). All patterns use real createClient from @supabase/supabase-js and Supabase CLI commands.

Prerequisites

• Supabase project with supabase CLI installed and linked
• @supabase/supabase-js v2+ installed
• CI/CD pipeline (GitHub Actions recommended)
• Database access via psql or Supabase SQL Editor
• Pro plan recommended for cost alerts and usage API

Instructions

Step 1 — Shared RLS Policy Library and Naming Conventions

RLS Policy Templates

Create reusable RLS policy templates that teams apply to new tables. This prevents each developer from writing ad-hoc policies and ensures consistent access control.

-- supabase/migrations/00000000000000_rls_policy_library.sql
-- Shared RLS policy library — apply these templates to new tables

-- ============================================================
-- Template 1: Owner-only access (user owns the row)
-- Usage: tables with a user_id column (todos, profiles, settings)
-- ============================================================
CREATE OR REPLACE FUNCTION public.rls_owner_only(table_name text, user_column text DEFAULT 'user_id')
RETURNS void AS $$
BEGIN
  EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', table_name);

  EXECUTE format(
    'CREATE POLICY "owner_select" ON public.%I FOR SELECT USING (%I = auth.uid())',
    table_name, user_column
  );
  EXECUTE format(
    'CREATE POLICY "owner_insert" ON public.%I FOR INSERT WITH CHECK (%I = auth.uid())',
    table_name, user_column
  );
  EXECUTE format(
    'CREATE POLICY "owner_update" ON public.%I FOR UPDATE USING (%I = auth.uid())',
    table_name, user_column
  );
  EXECUTE format(
    'CREATE POLICY "owner_delete" ON public.%I FOR DELETE USING (%I = auth.uid())',
    table_name, user_column
  );
END;
$$ LANGUAGE plpgsql;

-- ============================================================
-- Template 2: Organization-scoped access (user is member of org)
-- Usage: tables with org_id referencing org_members
-- ============================================================
CREATE OR REPLACE FUNCTION public.rls_org_scoped(
  table_name text,
  org_column text DEFAULT 'org_i…

Supabase Production Deployment Checklist

Overview

Actionable 14-step checklist for taking a Supabase project to production, based on Supabase's official production guide. Each step below carries its verification checklist inline; the full SQL, TypeScript, and CLI commands for every step live in references/step-commands.md.

Prerequisites

• 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

Work top to bottom. Every checkbox must be satisfied before go-live. Each step names the commands to run; copy them from references/step-commands.md.

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. Start with the audit query — it must return zero rows before going live:

-- Find tables WITHOUT RLS enabled (must return zero rows before launch)
SELECT schemaname, tablename, rowsecurity
FROM pg_tables
WHERE schemaname = 'public' AND rowsecurity = false;

Then ALTER TABLE ... ENABLE ROW LEVEL SECURITY and add per-command policies — full CREATE POLICY patterns in step-commands.md.

• [ ] 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. See the two-client setup in …

Supabase Rate Limits

Overview

Supabase enforces rate limits and quotas across every API surface — PostgREST, Auth, Storage, Realtime, and Edge Functions — and the numbers scale by plan tier. This skill gives you the exact per-tier limits, connection pooling via Supavisor, retry/backoff and pagination patterns, and dashboard monitoring so you stay within quota and handle 429 errors gracefully.

Prerequisites

• Active Supabase project (any tier)
• @supabase/supabase-js v2+ installed
• Project URL and anon/service-role key available
• Node.js 18+ or equivalent runtime

Instructions

Step 1 — Know your tier limits

Rate limits differ per surface and per plan. The headline API limits:

Auth, Storage, Realtime, Edge Functions, and Database connections each carry their own quotas. See the full per-surface breakdown in rate-limit-tiers.md before you architect.

Step 2 — Pool connections with Supavisor

Supavisor is Supabase's built-in connection pooler (replaced PgBouncer). Pick the mode by workload:

Transaction mode (port 6543) returns a connection to the pool after each transaction — the right default for serverless. Session mode (port 5432) holds a dedicated connection for LISTEN/NOTIFY and prepared statements. Full client setup and connection-string formats are in implementation.md.

Step 3 — Retry, paginate, and batch

Wrap queries in an exponential-backoff retry that recognizes 429s and pool exhaustion:

// Retryable when the error is a rate limit, "too many requests",
// code 429, or PGRST000 (connection pool exhausted). Delay doubles
// per attempt with jitt…

Supabase Reference Architecture

Overview

Production Supabase applications need more than a flat lib/supabase.ts file. This skill covers five enterprise architecture patterns: monorepo with shared types, multi-tenant RLS isolation, microservices with separate Supabase projects, framework integration (Next.js / SvelteKit), and operational patterns (edge functions, caching, queues, audit trails). Each pattern stands alone — pick the ones that match your scale.

For the full monorepo directory layout and microservices cross-project access, see Project Structure. For edge functions, caching, queue, and audit trail patterns, see Operational Patterns.

Prerequisites

• @supabase/supabase-js v2+ installed (npm install @supabase/supabase-js)
• Supabase CLI installed (npm install -g supabase)
• A Supabase project at supabase.com/dashboard
• Familiarity with supabase-install-auth (project URL, anon key, service role key)
• PostgreSQL basics (RLS policies, triggers, functions)

Instructions

Step 1: Client Singleton — The Foundation

Every app in the monorepo imports from a shared package instead of creating its own client. This guarantees a single source of truth for the URL, keys, and type definitions.

// packages/supabase/src/client.ts
import { createClient, SupabaseClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

let client: SupabaseClient<Database> | null = null

export function getSupabaseClient(): SupabaseClient<Database> {
  if (!client) {
    const url = process.env.NEXT_PUBLIC_SUPABASE_URL ?? process.env.SUPABASE_URL
    const key = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ?? process.env.SUPABASE_ANON_KEY
    if (!url || !key) {
      throw new Error('Missing SUPABASE_URL or SUPABASE_ANON_KEY environment variables')
    }
    client = createClient<Database>(url, key)
  }
  return client
}

// Reset for testing
export function resetClient(): void {
  client = null
}

// packages/supabase/src/admin.ts — Server-side only, never bundle in client code
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

export function getSupabaseAdmin() {
  const url = process.env.SUPABASE_URL
  const serviceKey = process.env.SUPABASE_SERVICE_ROLE…

Supabase Reliability Patterns

Overview

Production Supabase apps need six reliability layers: circuit breakers (stop calling Supabase when it's down to prevent cascading failures), offline queue (buffer writes when the network is unavailable and replay when reconnected), graceful degradation (serve cached or fallback data during outages), health checks (detect Supabase availability before routing traffic), retry with exponential backoff (handle transient errors without overwhelming the service), and dual-write (write critical data to both Supabase and a backup store). All patterns use real createClient from @supabase/supabase-js.

Prerequisites

• @supabase/supabase-js v2+ installed
• TypeScript project with Supabase client configured
• For offline queue: browser environment with IndexedDB or server with Redis
• For dual-write: secondary data store (Redis, DynamoDB, or local SQLite)

Instructions

Step 1 — Circuit Breaker and Retry with Exponential Backoff

A circuit breaker tracks failures per Supabase service (database, auth, storage) and stops making calls when a threshold is exceeded. Combined with retry logic, it prevents both cascading failures and unnecessary retries during extended outages.

Circuit Breaker Implementation

// lib/circuit-breaker.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN'

interface CircuitBreakerOptions {
  failureThreshold: number    // failures before opening
  resetTimeoutMs: number      // ms before trying again (half-open)
  halfOpenSuccesses: number   // successes in half-open to close
  name: string                // for logging
}

class CircuitBreaker {
  private state: CircuitState = 'CLOSED'
  private failures = 0
  private lastFailureTime = 0
  private halfOpenSuccesses = 0

  constructor(private opts: CircuitBreakerOptions) {}

  async call<T>(fn: () => Promise<T>, fallback?: () => T): Promise<T> {
    // Check if circuit should transition from OPEN to HALF_OPEN
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailureTime > this.opts.resetTimeoutMs) {
        this.state = 'HALF_OPEN'
        this.halfOpenSuccesses = 0
        console.log(`[CircuitBreaker:${this.opts.name}] OPEN → HALF_OPEN`)
      } else {
        if (fallback) return fallback()
        throw new Error(`Circuit breaker ${this.opts.name} is OPEN`)
      }
    }

    try {
      const result = await fn()

      // Success in HALF_OPEN: count toward recovery
      if (this.state === 'HALF_OPEN') {
        this.halfOpenSuccesses++
   …

Supabase Schema from Requirements

Overview

Translate business requirements into a production-ready Postgres schema inside Supabase, covering the full path from specification to applied migration: entity extraction, tables with proper types and constraints, Row Level Security policies, performance indexes, timestamp triggers, and TypeScript type generation. Getting this right early matters because every downstream feature — auth, storage, realtime, edge functions — depends on well-designed tables.

Prerequisites

• Supabase CLI installed (npm install -g supabase) and project linked (supabase link)
• @supabase/supabase-js v2+ installed in the project
• Business requirements, PRD, or specification document identifying entities and access rules
• Local Supabase running (supabase start) or a linked remote project

Instructions

Step 1: Parse Requirements and Create Migration

Read the requirements document and extract entities, attributes, relationships, and access control rules. Map each entity to a Postgres table.

Entity extraction example (project management app):

Create the migration file:

npx supabase migration new create_tables
# Creates: supabase/migrations/TIMESTAMP_create_tables.sql

Write the migration SQL using standard Postgres data types (uuid, text, integer, boolean, timestamptz, jsonb): Full worked migration (project-management app — tables, FKs, indexes, moddatetime triggers): references/worked-schema-examples.md.

Data type selection guide:

Supabase SDK Patterns

Overview

Production patterns for @supabase/supabase-js v2 and supabase-py, where every call returns { data, error } and success is never assumed. Covers client initialization, CRUD with filters, auth, realtime, storage, and RPC, with Python equivalents for the query patterns.

Prerequisites

• Supabase project with URL and anon key (or service role key for server-side)
• @supabase/supabase-js v2 installed (TypeScript) or supabase pip package (Python)
• TypeScript projects: generated database types via supabase gen types typescript

Instructions

Step 1: Initialize a typed singleton client

Create one client instance and reuse it. Never call createClient per-request — a singleton preserves the auth session and connection pool.

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

let supabase: ReturnType<typeof createClient<Database>>

export function getSupabase() {
  if (!supabase) {
    supabase = createClient<Database>(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_ANON_KEY!,
      {
        auth: { autoRefreshToken: true, persistSession: true },
        db: { schema: 'public' },
        global: { headers: { 'x-app-name': 'my-app' } },
      }
    )
  }
  return supabase
}

Python equivalent:

from supabase import create_client, Client

_client: Client | None = None

def get_supabase() -> Client:
    global _client
    if _client is None:
        _client = create_client(
            os.environ["SUPABASE_URL"],
            os.environ["SUPABASE_ANON_KEY"],
        )
    return _client

Step 2: Query, filter, and mutate data

Destructure { data, error } and check error before touching data. Chain filters onto .from(table).select(...); use .select().single() after an insert/upsert to return the affected row. Skeleton:

const { data, error } = await getSupabase()
  .from('users')
  .select('id, name, email')
  .eq('active', true)
  .order('name')
  .limit(10)

if (error) throw error

For the full CRUD set (insert-with-select, upsert on conflict, update, delete, RPC), the complete 12-filter reference table, and the Python equivalents, see queries and filters.

Step 3: Auth, realtime, and storage

Auth, realtime channels, and …

Supabase Security Basics

Overview

Supabase exposes a Postgres database directly to the internet via PostgREST. Every table without Row Level Security enabled is fully readable and writable by anyone with your project URL and anon key — both of which are public. This skill covers the three pillars of Supabase security: key separation (anon vs service_role), RLS policy enforcement, and API surface hardening.

Prerequisites

• Supabase project created (local or hosted) with Dashboard access
• @supabase/supabase-js installed (npm install @supabase/supabase-js)
• SUPABASE_URL and SUPABASE_ANON_KEY environment variables configured
• Basic understanding of SQL and Postgres

Instructions

Step 1 — Understand the Two API Keys

Supabase issues two keys per project. Confusing them is the most common security mistake:

The anon key is a JWT that PostgREST uses to determine which RLS policies apply. It is safe to include in client-side bundles — it can only access data that RLS policies explicitly allow. The service role key bypasses every RLS policy and should only ever exist in server-side code (API routes, Edge Functions, cron jobs, migration scripts).

// CORRECT: anon key on the client
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

// CORRECT: service role key ONLY in server-side code
// e.g., app/api/admin/route.ts (Next.js server route)
import { createClient } from '@supabase/supabase-js'

const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { autoRefreshToken: false, persistSession: false } }
)

// WRONG — service role key in client-side code
// This bypasses ALL RLS and leaks your admin key to every user
const supabase = createClient(url, process.env.NEXT_PUBLIC_SERVICE_ROLE_KEY!)  // NEVER DO THIS

Key rotation: Regenerate keys in Dashboard > Settings > API. After rotation, update every environment variable and redeploy all services. Old keys are invalidated immediately — there is no grace period.

Step 2 — Enforce Row Level Security on Every Table

Without…

Supabase Upgrade Migration

Overview

Upgrade @supabase/supabase-js and the Supabase CLI with breaking-change detection, automated code migration, and rollback planning. Covers the v1-to-v2 migration path (auth method renames, data/error destructuring, realtime API overhaul), minor version bumps, @supabase/ssr adoption, and Python SDK upgrades via pip install --upgrade supabase.

Current State

!npm list @supabase/supabase-js 2>/dev/null | grep supabase || echo 'supabase-js not installed' !supabase --version 2>/dev/null || echo 'CLI not installed' !pip show supabase 2>/dev/null | grep Version || echo 'Python SDK not installed'

Prerequisites

• @supabase/supabase-js or the Python supabase package installed in the project
• Git with a clean working tree (no uncommitted changes)
• Test suite available for post-upgrade verification
• Node.js >= 18 (for supabase-js v2) or Python >= 3.8 (for Python SDK)

Instructions

Step 1: Audit Versions, Scan Usage, and Review Breaking Changes

Check every installed Supabase package and find all import sites in the codebase.

# Check current SDK version
npm list @supabase/supabase-js

# Check CLI version
supabase --version

# Check Python SDK version
pip show supabase | grep Version

# Find all JS/TS Supabase imports
grep -rn "from '@supabase/supabase-js'" --include="*.ts" --include="*.tsx" --include="*.js" src/ lib/ app/ 2>/dev/null
grep -rn "createClient" --include="*.ts" --include="*.tsx" --include="*.js" src/ lib/ app/ 2>/dev/null

# Find all Python Supabase imports
grep -rn "from supabase" --include="*.py" src/ app/ 2>/dev/null

supabase-js v1 → v2 breaking changes:

Supabase Webhooks & Database Events

Overview

Supabase offers four complementary event mechanisms: Database Webhooks (trigger-based HTTP calls via pg_net), supabase_functions.http_request() (call Edge Functions from triggers), Postgres LISTEN/NOTIFY (lightweight pub/sub), and Realtime postgres_changes (client-side event subscriptions). This skill covers all four patterns with production-ready code including signature verification, idempotency, and retry handling.

Prerequisites

• Supabase project (local or hosted) with supabase CLI installed
• pg_net extension enabled: Dashboard > Database > Extensions > search "pg_net" > Enable
• @supabase/supabase-js v2+ installed for client-side patterns
• Edge Functions deployed for webhook receiver patterns

Authentication

Both directions of a webhook are authenticated:

• Outbound (trigger → Edge Function): the trigger sends an Authorization: Bearer <service_role_key> header. Store the key in a Postgres setting (app.settings.service_role_key) or Supabase Vault — never inline it in a committed migration.
• Inbound (Edge Function receiver): verify an HMAC-SHA256 signature against a shared WEBHOOK_SECRET (read from Deno.env) using a constant-time comparison, and reject mismatches with 401. See signature-verification.md.

Instructions

Pick the mechanism that fits the consumer: pg_net triggers for server-side HTTP fan-out, Edge Function receivers for signed processing, LISTEN/NOTIFY for in-database pub/sub, and Realtime for client UI. Write each SQL trigger to a supabase/migrations/ file and each handler to supabase/functions/<name>/index.ts, then apply and deploy with the supabase CLI.

Step 1 — Database Webhooks with pg_net and Trigger Functions

Enable pg_net, then write a trigger function that POSTs the changed row to an Edge Function. Attach it AFTER INSERT/UPDATE/DELETE. Full trigger set (conditional status-change trigger, the supabase_functions.http_request() built-in helper, and net._http_response inspection queries) is in database-webhooks.md.

CREATE EXTENSION IF NOT EX…