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 auth.jwt() -> 'app_metadata' ->> 'role' and ... ->> 'org_id'. Wrap the JWT extrac

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 dashboard to visually confirm the row is there. See implementation.md for the fully error-handled v

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,
       max(extract(epoch FROM age(now(), state_change)))::int AS max_idle_seconds
FROM pg_stat_activity
WHERE datname = current_database()
GROUP BY state ORDER BY connections DESC;
-- WARNING: If idle > 20 or idle_in_transaction > 0, you have a leak

From there, drill into

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):

// lib/supab