RonanCodes/skills/supabase

Supabase

CLI + Management-API ops for Supabase: projects, linking, migrations, TS types, RLS, and local dev. Postgres + Auth + Row Level Security in one. Reach for this over neon when you want auth and storage bundled with the database and RLS-enforced multi-tenant / multi-role access, or when the target stack is Supabase (e.g. a Next.js + Supabase + Vercel app).

Usage

/ro:supabase install                         # wire @supabase/supabase-js (+ @supabase/ssr for Next) into the current app
/ro:supabase project list
/ro:supabase project create <name> --org <id>  # create a hosted project, print URL + anon/service keys
/ro:supabase link --project <ref>            # link the cwd app to a hosted project
/ro:supabase migrate new <name>              # create a new migration file
/ro:supabase migrate up                      # apply migrations locally
/ro:supabase db-push                          # push local migrations to the linked hosted project
/ro:supabase types                            # generate src/types/database.ts from the schema
/ro:supabase rls                              # scaffold / review RLS policies (multi-role pattern)
/ro:supabase start | stop                     # local dev stack (Docker)

Prerequisites

• SUPABASE_ACCESS_TOKEN in ~/.claude/.env (personal token, sbp_...). Create/rotate at https://supabase.com/dashboard/account/tokens. Always grep ~/.claude/.env for it before asking the user to paste one.
• supabase CLI: brew install supabase/tap/supabase (check which supabase first; install only with the user's ok).
• For start / local dev: Docker running.

Load the token into the shell for any CLI/API call:

export SUPABASE_ACCESS_TOKEN=$(grep -E '^SUPABASE_ACCESS_TOKEN=' ~/.claude/.env | cut -d= -f2-)

Management API (projects)

Base https://api.supabase.com/v1, auth Authorization: Bearer $SUPABASE_ACCESS_TOKEN.

# list projects
curl -s https://api.supabase.com/v1/projects -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" | jq -r '.[] | "\(.id)  \(.name)  \(.region)"'

# list orgs (need the org id to create a project)
curl -s https://api.supabase.com/v1/organizations -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" | jq

# create a project (EU region for personal/Simplicity work; prompt for a db password)
curl -s -X POST https://api.supabase.com/v1/projects \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"<name>","organization_id":"<org>","region":"eu-central-1","db_pass":"<generated>","plan":"free"}' | jq

Structural-change guard

Before any of these, prompt the user (AskUserQuestion) with what will happen, since they never invoke the skill internals directly:

• installing the CLI or running pnpm add,
• creating a hosted project (costs/quota),
• db-push (mutates the remote schema),
• supabase start (spins up Docker containers).

Never run db-push against a linked production project without an explicit confirm.

Install into a Next.js app (the common path)

1. pnpm add @supabase/supabase-js @supabase/ssr
2. supabase init (creates supabase/ with config + migrations).
3. Env (.env.local): NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, and server-only SUPABASE_SERVICE_ROLE_KEY. Never expose the service-role key to the client.
4. Scaffold a browser client and a server client (@supabase/ssr createServerClient / createBrowserClient) and middleware for auth session refresh.
5. /ro:supabase types to generate typed rows.

RLS (the part that earns the points)

RLS is Supabase's headline feature and the right way to enforce per-role and per-tenant access in the database, not the app layer. Default deny, then add policies.

alter table bids enable row level security;

-- adviser: full access to bids on their own listings
create policy "adviser_reads_own_listing_bids" on bids for select
  using (
    exists (select 1 from listings l
            where l.id = bids.listing_id and l.adviser_id = auth.uid())
  );

-- bidder (client): only their own bid
create policy "bidder_reads_own_bid" on bids for select
  using (bidder_id = auth.uid());

-- admin: all rows in their agency
create policy "admin_reads_agency_bids" on bids for select
  using (
    exists (select 1 from profiles p
            where p.id = auth.uid() and p.role = 'admin'
              and p.agency_id = (select agency_id from listings where id = bids.listing_id))
  );

Pattern notes:

• Put role and agency_id on a profiles table keyed by auth.uid(); policies read from it.
• Scale isolation: enforce per-agency as well as per-role, so growth never leaks data across tenants.
• Keep policies in a migration so they go through the migration review gate, not ad hoc in the dashboard.
• Test each role with supabase local + a seeded user per role.

Generate types

supabase gen types typescript --linked > src/types/database.ts   # or --project-id <ref>

Reconcile a drifted live schema (out-of-band DDL)

When tables were applied directly to the live DB (e.g. DDL run against the direct host db.<ref>.supabase.co:5432 because the pooler rejects DDL) they never enter your migration history or ORM schema file — so the repo's "source of truth" silently drifts from production. Symptom: an app where some tables exist in code (Drizzle schema.ts / migrations) and others only live in Supabase. Reconcile BEFORE writing the next migration, or you'll generate a diff against a stale baseline.

# 1. Capture the live schema as the truth
supabase db pull                                   # writes a migration reflecting live state
#    — or, if Drizzle is the schema source of truth:
npx drizzle-kit pull                               # introspects the live DB → regenerates schema.ts
# 2. Regenerate TS types from the reconciled schema
supabase gen types typescript --linked > src/types/database.ts
# 3. Inspect anything code never touches (columns/constraints/RPCs added out of band)
pg_dump --schema-only "postgresql://...@db.<ref>.supabase.co:5432/postgres"

RLS policies and Postgres functions/RPCs (e.g. *_rebuild_* procedures) live only in SQL — db pull captures them into a migration, but drizzle-kit pull does NOT model them, so keep those as SQL migrations regardless. Only after reconciling is the next migrate new diff trustworthy.

When to choose Supabase vs Neon

• Supabase: want Auth + storage + RLS bundled; multi-role / multi-tenant apps; a dashboard; the target stack is already Supabase (e.g. Next + Vercel).
• Neon: Postgres only, serverless HTTP driver for Cloudflare Workers, per-PR DB branches, no need for bundled auth. See [/ro:neon].

Pairs with

• [/ro:better-auth] if you want identity in your own tables instead of Supabase Auth.
• Vercel for deploy (store VERCEL_TOKEN in ~/.claude/.env).
• The HousApp Bieden build (Next + Supabase + Vercel, RLS per role) is the canonical use case.