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. | Key | Where it lives | RLS | If it leaks | |-----|----------------|-----|-------------| | **anon** / **publishable** (`sb_publishable_...`) | Browser, public env (`NEXT_PUBLIC_*`) | **Enforced** — safe in client only because RLS gates rows | Low: attacker still bound by your policies | | **service_role** / **secret** (`sb_secret_...`) | Server only — Edge Functions, server env, never bundled | **Bypassed entirely** | Catastrophic: full read/write of all data | 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. ```ts // 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 | Context | Package | Where it lives | |---------|---------|----------------| | Browser-only SPA | `@supabase/supabase-js` (`createClient`) | Client bundle, anon key | | Next.js / SvelteKit / Remix (SSR) | `@supabase/ssr` (`createBrowserClient` + `createServerClient`) | One client per context + middleware | | Server job / Edge Function | `@supabase/supabase-js` with service_role from env | Server only | 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 | Situation | Use | Why | |-----------|-----|-----| | New project (asymmetric keys), gating a page or route | **`getClaims()`** | Local JWK signature check, zero latency per call — the documented default | | Legacy project still on a **symmetric** JWT secret | `getClaims()` (auto-fallback) | With no public key to verify, `getClaims()` *itself* calls the Auth server — same cost as `getUser()`, so still the right default | | You must detect a **just-banned / just-deleted** user mid-session | `getUser()` | Local verification trusts a still-valid signature; only a server round-trip sees a revoked user. Higher cost, stricter guarantee | ```ts // 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](references/auth-ssr.md). For the framework's own RSC/caching/server-action mechanics see [../nextjs/SKILL.md](../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. ```sql -- 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](references/rls-cookbook.md). For engine-level index choice and EXPLAIN reading, see [../postgresdb/SKILL.md](../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`. ```ts // 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. | Feature | Use for | Scaling | |---------|---------|---------| | **Broadcast** | Ephemeral messages (chat, cursors, custom events) | Scales for high fan-out; preferred default | | **Presence** | Who's online / shared cursor state | Backed by Broadcast machinery | | **Postgres Changes** | WAL-based row insert/update/delete events | Does **not** fan out well at scale | > 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). ```ts 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. ```ts // 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](../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 | Anti-pattern | Why it's wrong | Do instead | |--------------|----------------|------------| | `service_role`/`sb_secret_` in a client component or `NEXT_PUBLIC_*` | Bypasses RLS → full data breach | Keep it server-only; browser uses anon/publishable | | Authorizing with `getSession()` on the server | Reads an unverified cookie; spoofable | `getClaims()` — verifies the JWT signature locally (`getUser()` only when you need live ban/delete detection) | | "I'll disable RLS for now" | An exposed table with RLS off is world-readable via the anon key | Enable RLS + write a permissive policy instead | | Bare `auth.uid()` in a policy | Re-evaluated per row → table-scan latency | `(select auth.uid())` + index the column | | Postgres Changes for chat / high fan-out | Doesn't scale; backpressure and dropped events | Broadcast (incl. broadcast-from-database triggers) | | Empty results "must be RLS" | Often the table isn't exposed to the data API (2026 default flip) | Check Data API exposure first, then policies | | Using `@supabase/auth-helpers` | Deprecated | Migrate to `@supabase/ssr` | | service_role client inside an Edge Function for normal user work | Silently bypasses RLS for everyone | Forward the caller's `Authorization` header | --- ## 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`.