Supabase

Supabase — Postgres with RLS as the auth layer

Supabase is a managed Postgres database wrapped in thin SDKs, a PostgREST data API, Auth, Storage, Realtime, and Deno Edge Functions. The one sentence that explains every footgun below:

Your authorization lives in the database (Row Level Security), not in your app code.

The browser holds a key that can hit your database directly. That is safe only because RLS gates every row. Get that wrong and you either leak everything or see nothing. Everything in this skill is downstream of that fact. You can write SQL already — what you need is Supabase's specific abstractions and where the trust boundary sits.

Use the current packages: @supabase/supabase-js v2 (v1 is security-fixes only) and @supabase/ssr for server frameworks (it replaced the deprecated auth-helpers).

The two keys (the trust boundary)

Every Supabase project ships two classes of key. Confusing them is the one unrecoverable mistake.

The new sb_publishable_ / sb_secret_ format is rolling out alongside the legacy anon/service_role JWTs; treat them by the same rules. Why this matters: the service_role key is a master key with RLS turned off. One import into a client component is a full data breach.

// Bad — service_role key reachable from the browser bundle
"use client";
const supabase = createClient(URL, process.env.NEXT_PUBLIC_SERVICE_ROLE_KEY!); // leaked

// Good — service_role only in server-side env, never NEXT_PUBLIC_*
// server-only module / Edge Function:
const admin = createClient(URL, process.env.SUPABASE_SERVICE_ROLE_KEY!);

Pick your client

Wrong client = broken sessions (no cookie refresh) or leaked keys. For SSR frameworks you need both an @supabase/ssr browser client and a server client, plus middleware — see below.

Auth that actually protects

Cookie-based auth in an SSR framework has one hard constraint: Server Components cannot write cookies, so an expired access token can only be refreshed in middleware. Skip the middleware and sessions silently die mid-request.

The non-negotiable rule for server-side gating: never trust getSession() — it only reads the cookie, which a client can forge. What you reach for instead changed in late 2025.

Default: supabase.auth.getClaims(). It verifies the JWT signature locally against your project's published public keys (/.well-known/jwks.json, cached on the edge and in memory) — no network round-trip. The current SSR docs say to "always use supabase.auth.getClaims() to protect pages and user data." This works because new projects sign tokens with asymmetric keys by default since 2025-10-01 (RSA or Elliptic-Curve / ECC); the private key never leaves Auth, the public key is safe to verify with.

getClaims vs getUser — pick by signing key + freshness need

// Bad — getSession reads an unverified cookie; trivially spoofed
const { data: { session } } = await supabase.auth.getSession();
if (!session) redirect("/login"); // NOT a real check on the server

// Good (default) — getClaims verifies the JWT signature locally, no round-trip
const { data } = await supabase.auth.getClaims();
if (!data?.claims) redirect("/login");

// Good (strict fallback) — getUser revalidates against the Auth server every call;
// use only when you need live ban/delete detection
const { data: { user } } = await supabase.auth.getUser();
if (!user) redirect("/login");

Middleware token refresh is mandatory; full app-router code (browser client, server client, middleware.ts, server-action sign-in/out, OAuth/PKCE callback, and the auth-helpers→@supabase/ssr migration checklist) lives in references/auth-ssr.md. For the framework's own RSC/caching/server-action mechanics see ../nextjs/SKILL.md — this skill only covers the Supabase wiring inside it.

RLS recipes + the performance cliff

Enable RLS on every table the data API can reach, then write policies. Four rules that cover most real cases:

1. enable row level security on the table — without it, an exposed table is wide open to the anon key.
2. Scope with to authenticated — don't rely on auth.uid() alone to exclude the anon role; an anon request has a null uid and may slip through a sloppy predicate.
3. Wrap (select auth.uid()) — Postgres caches a select-wrapped call once per statement instead of re-evaluating per row. Bare auth.uid() turns a lookup into a per-row function call → table-scan latency.
4. Index the policy columns — a policy filtering user_id = (select auth.uid()) needs an index on user_id, or every query scans the table.

-- Bad — bare auth.uid() re-evaluated per row, no role scope, no index
create policy "owner reads" on documents
  for select using ( user_id = auth.uid() );

-- Good — cached subquery, role-scoped; pair with an index
create policy "owner reads" on documents
  for select to authenticated
  using ( user_id = (select auth.uid()) );

create index on documents (user_id);

For cross-table checks (is the user a member of this org?), use a security definer helper or a team_id filter rather than a correlated subquery inside the policy. Multi-tenant team_id patterns, public-read/private-write, storage policies, realtime.messages policies, and how to test policies with set role authenticated live in references/rls-cookbook.md. For engine-level index choice and EXPLAIN reading, see ../postgresdb/SKILL.md.

"My query returns nothing" — checklist

Silent empty results are the #1 confusion. Walk it in order:

1. Is RLS enabled but you have no policy? No policy = deny all. Add a select policy.
2. Is the policy too strict / role-scoped wrong? Test it: set role authenticated; with a faked request.jwt.claims (see the cookbook).
3. Is the table even exposed to the data API? This is the new trap. Supabase is flipping the "automatically expose new tables" default off: default for new projects since 2026-05-30, and enforced on all existing projects 2026-10-30. An unexposed table is unreachable through PostgREST even with perfect RLS — you get empty results, not an error. Expose it explicitly in the dashboard (Data API settings) or grant access in the relevant schema.

Storage

Buckets hold objects; access is governed by RLS policies on the storage.objects table — the same engine as table RLS.

• Public bucket: objects served via a stable public URL, no auth. Good for avatars, bad for anything private.
• Private bucket: reads require a signed URL (createSignedUrl, time-limited) or an authed request that passes a policy.

Why this bites: a "public" bucket with no upload policy is either world-writable or fully closed depending on your defaults. Always write explicit insert/select policies on storage.objects.

// Client upload (anon key) — RLS on storage.objects decides if it is allowed
await supabase.storage.from("avatars").upload(`${user.id}/photo.png`, file);

// Private read — short-lived signed URL, not a public link
const { data } = await supabase.storage.from("docs").createSignedUrl(path, 60);

Realtime — default to Broadcast

Three features, and the choice between them is a scaling decision teams get wrong.

Default to Broadcast. Reach for Postgres Changes only for low-volume row-event needs.

For row changes that must reach many clients, use "broadcast from the database" — a trigger that calls realtime.broadcast_changes/realtime.send — instead of Postgres Changes. Private channels are authorized by RLS policies on the realtime.messages table (Broadcast and Presence support this).

const channel = supabase.channel("room:42", { config: { private: true } });
channel
  .on("broadcast", { event: "msg" }, ({ payload }) => render(payload))
  .subscribe();
channel.send({ type: "broadcast", event: "msg", payload: { text: "hi" } });

Edge Functions

Edge Functions are Deno/TypeScript, deployed globally. The runtime injects SUPABASE_URL, SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY.

• Scaffold: supabase functions new my-fn. Each function may carry its own deno.json/deno.jsonc (requires CLI ≥ v1.215.0).
• Secrets: supabase secrets set MY_KEY=... (don't commit them).
• Forward the caller's JWT so RLS still applies: read the request's Authorization header and pass it into a per-request client. A function that uses the service_role client silently bypasses all RLS — only do that for genuinely trusted admin work.

// Good — per-request client carries the user's JWT; RLS enforced
const supabase = createClient(
  Deno.env.get("SUPABASE_URL")!,
  Deno.env.get("SUPABASE_ANON_KEY")!,
  { global: { headers: { Authorization: req.headers.get("Authorization")! } } },
);

Handle CORS for browser invocations (return Access-Control-Allow-* and answer the OPTIONS preflight).

Local dev & migrations

• supabase init → supabase start (local stack) → supabase link --project-ref <ref>.
• Generate migrations from local changes with supabase db diff rather than editing prod schema in the dashboard (the dashboard drifts from source control).
• Declarative schema (experimental): describe schema as SQL files and let supabase db diff generate the migration via the pg-delta diff engine.
• Seed local data via supabase/seed.sql.

For migration discipline (expand-contract, concurrent indexes, batched backfills) the general practice lives in ../db-migrations/SKILL.md; for ORM-managed schema on top of Supabase Postgres see ../drizzle-orm/SKILL.md.

Note: pg_graphql is disabled by default on new projects (since Feb 2026) — enable it if you need it.

Anti-patterns

Verify

Run bash scripts/verify.sh from a Supabase-backed repo. It hard-fails on service_role/sb_secret_ leaking into client-reachable files and warns on getSession() used for gating, bare auth.uid() in policies, and create table migrations missing enable row level security.