supabase

---
name: supabase
description: "Use when building a backend on Supabase: Postgres database, auth, storage, realtime, and edge functions accessed via the JS client or CLI."
source: https://supabase.com/docs
generated: 2026-07-02T18:43:31.654Z
category: platform
audience: engineers
---

## When to use

- Adding Postgres-backed auth, storage, or realtime to a web or mobile app
- Managing schema, migrations, and local dev with the Supabase CLI
- Querying or mutating data through supabase-js with row level security
- Deploying Edge Functions for server-side logic

## Key concepts

### Row Level Security (RLS)

Postgres policies enforced per-row. Disabled by default on new tables; the anon and authenticated roles can read/write everything until you enable RLS and add policies.

### anon vs service_role key

The anon key is safe to ship in clients and is constrained by RLS; the service_role key bypasses RLS entirely and must only be used server-side.

### supabase-js client

Isomorphic JS SDK wrapping PostgREST (db), GoTrue (auth), Storage, and Realtime under one createClient instance.

### Migrations

SQL files in supabase/migrations applied in timestamp order. Created with `supabase migration new` and pushed to remote with `supabase db push`.

### Local stack

`supabase start` runs the full stack (Postgres, Studio, Auth, Storage) in Docker for offline development that mirrors production.

### Edge Functions

Deno-based serverless functions deployed to the edge, used for webhooks, custom auth logic, and server-only secrets.

## API reference

```
createClient(supabaseUrl, supabaseKey, options?)
```

Instantiate the JS client used for db, auth, storage, and realtime.

```
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
)
```

```
supabase.from(table).select(columns).eq(col, val)
```

Query rows via PostgREST with filters, ordering, and joins.

```
const { data, error } = await supabase
  .from('profiles')
  .select('id, username')
  .eq('id', userId)
  .single()
```

```
supabase.auth.signInWithPassword({ email, password })
```

Authenticate a user and persist the session.

```
const { data, error } = await supabase.auth.signInWithPassword({
  email: 'a@b.com',
  password: 'secret'
})
```

```
supabase init  /  supabase start  /  supabase db push
```

CLI: scaffold project config, run the local Docker stack, and apply migrations to the linked remote.

```
supabase init
supabase start
supabase migration new create_profiles
supabase db push
```

## Gotchas

- New tables have RLS disabled, so the anon key can read/write all rows until you enable RLS and write policies.
- Never expose the service_role key in client code; it bypasses every RLS policy.
- supabase-js returns { data, error } and does not throw on query errors; you must check error explicitly.
- `.single()` errors if zero or more than one row matches; use `.maybeSingle()` when zero is valid.
- `supabase db push` only applies new migration files, not ad-hoc Studio changes; capture schema edits with `supabase db diff`.
- Local `supabase start` requires Docker running and uses fixed default ports that can collide with other services.
- Email confirmations are on by default, so newly signed-up users have no session until they confirm.

---
Generated by SkillMake from https://supabase.com/docs on 2026-07-02T18:43:31.654Z.
Verify against source before relying on details.

File: ~/.claude/skills/supabase/SKILL.md