Supabase Cheatsheet: Postgres, Auth, Storage and Realtime

# 1. CLI — global install
brew install supabase/tap/supabase     # or: npm i -g supabase

supabase --version
supabase login                          # opens browser for the access token

# 2. New project — local stack (Docker)
supabase init                           # scaffold supabase/ folder
supabase start                          # boot Postgres + Studio + GoTrue + Realtime locally
supabase status                         # prints URLs + anon/service_role keys

# 3. Link to a cloud project
supabase link --project-ref xxxxxxxxxxxx
supabase db push                        # apply local migrations to the cloud DB

# 4. JS client (browser / Node / Bun / Deno)
npm i @supabase/supabase-js

# 5. Initialise the client
cat > supabase-client.ts <<'TS'
import { createClient } from '@supabase/supabase-js'

export const sb = createClient(
    import.meta.env.VITE_SUPABASE_URL!,
    import.meta.env.VITE_SUPABASE_ANON_KEY!,    // anon key — public, RLS-protected
)
TS

-- Owner-only access pattern: every row carries a user_id; users see only their own.
CREATE TABLE IF NOT EXISTS public.todos (
    id        bigserial PRIMARY KEY,
    user_id   uuid NOT NULL DEFAULT auth.uid() REFERENCES auth.users(id) ON DELETE CASCADE,
    title     text NOT NULL,
    done      boolean NOT NULL DEFAULT false,
    created   timestamptz NOT NULL DEFAULT now()
);

-- Step 1 — enable RLS (nothing in this table is visible until you do)
ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;

-- Step 2 — narrow policies, one per operation, USING vs WITH CHECK
CREATE POLICY todos_select_own ON public.todos
    FOR SELECT USING (user_id = auth.uid());

CREATE POLICY todos_insert_own ON public.todos
    FOR INSERT WITH CHECK (user_id = auth.uid());

CREATE POLICY todos_update_own ON public.todos
    FOR UPDATE USING (user_id = auth.uid())
                WITH CHECK (user_id = auth.uid());

CREATE POLICY todos_delete_own ON public.todos
    FOR DELETE USING (user_id = auth.uid());

-- Inspect what's in effect
SELECT schemaname, tablename, policyname, cmd, qual, with_check
FROM   pg_policies
WHERE  tablename = 'todos';

import { sb } from './supabase-client'

// All calls return { data, error } — always check error first.
const { data: open, error: e1 } = await sb
    .from('todos')
    .select('id, title, created, profiles(name)')        // embed FK relation
    .eq('done', false)
    .order('created', { ascending: false })
    .range(0, 19)                                        // pagination — 20 rows
if (e1) throw e1

// Insert + return the row(s) you just wrote
const { data: created } = await sb
    .from('todos')
    .insert({ title: 'Write supabase cheatsheet' })
    .select()
    .single()

// Upsert by primary key
await sb.from('todos').upsert(
    { id: created.id, done: true },
    { onConflict: 'id' }
)

// Update + filter combined
await sb.from('todos').update({ done: true }).eq('id', created.id)

// Delete
await sb.from('todos').delete().eq('id', created.id)

// Call a Postgres function — RLS still applies on its tables
const { data: top } = await sb.rpc('top_todos', { uid: (await sb.auth.getUser()).data.user!.id, n: 5 })

import { sb } from './supabase-client'

// 1. Email + password
const { data: signup, error } = await sb.auth.signUp({
    email:    'ada@example.com',
    password: 'correct horse battery staple',
})
const { data: session } = await sb.auth.signInWithPassword({
    email: 'ada@example.com', password: 'correct horse battery staple',
})

// 2. OAuth — Google, GitHub, Apple, ...
await sb.auth.signInWithOAuth({
    provider: 'google',
    options:  { redirectTo: `${window.location.origin}/auth/callback` },
})

// 3. Magic link / OTP (no password)
await sb.auth.signInWithOtp({ email: 'ada@example.com' })
// On the callback page:
await sb.auth.verifyOtp({ email: 'ada@example.com', token: '123456', type: 'email' })

// 4. Read the live session (persisted in localStorage / cookies)
const { data: { session: cur } } = await sb.auth.getSession()
const { data: { user }      } = await sb.auth.getUser()

// 5. React to auth changes anywhere in the app
const { data: sub } = sb.auth.onAuthStateChange((event, sess) => {
    if (event === 'SIGNED_IN')  navigate('/app')
    if (event === 'SIGNED_OUT') navigate('/login')
})
// later: sub.subscription.unsubscribe()

await sb.auth.signOut()

import { sb } from './supabase-client'

// Subscribe to INSERTs on todos for the current user.
const channel = sb
    .channel('todos:user')                              // any unique name per tab
    .on(
        'postgres_changes',
        {
            event:  'INSERT',
            schema: 'public',
            table:  'todos',
            filter: `user_id=eq.${userId}`,             // server-side filter
        },
        (payload) => {
            console.log('new row', payload.new)
        }
    )
    .on(
        'postgres_changes',
        { event: 'UPDATE', schema: 'public', table: 'todos', filter: `user_id=eq.${userId}` },
        (payload) => { console.log('updated', payload.old, '→', payload.new) }
    )
    .subscribe((status) => {
        if (status === 'SUBSCRIBED') console.log('listening')
    })

// Broadcast (peer-to-peer message bus) + presence (who is online)
channel
    .on('broadcast', { event: 'cursor' }, ({ payload }) => moveCursor(payload))
    .on('presence',  { event: 'sync'   }, () => setPeers(channel.presenceState()))

await channel.track({ user_id: userId, seen_at: new Date().toISOString() })
channel.send({ type: 'broadcast', event: 'cursor', payload: { x: 100, y: 120 } })

// Clean up when the component unmounts
sb.removeChannel(channel)

// End-to-end: auth-gated todo app. ~30 lines, RLS keeps each user's todos private.
import { sb } from './supabase-client'

async function main() {
    // 1. Sign in (or sign up — adapt as needed)
    await sb.auth.signInWithPassword({ email: 'ada@example.com', password: '****' })

    // 2. Insert — user_id defaults to auth.uid() via the DEFAULT clause + RLS WITH CHECK
    const { data: created, error } = await sb
        .from('todos')
        .insert({ title: 'Ship supabase cheatsheet' })
        .select().single()
    if (error) throw error

    // 3. Subscribe to my own INSERT/UPDATE/DELETE events
    const channel = sb.channel('my-todos')
        .on('postgres_changes',
            { event: '*', schema: 'public', table: 'todos',
              filter: `user_id=eq.${(await sb.auth.getUser()).data.user!.id}` },
            (p) => console.log(p.eventType, p.new ?? p.old))
        .subscribe()

    // 4. List — RLS limits the result to my rows only
    const { data: open } = await sb.from('todos')
        .select('*').eq('done', false).order('created', { ascending: false })

    // 5. Complete the todo
    await sb.from('todos').update({ done: true }).eq('id', created.id)

    // 6. Tidy up
    sb.removeChannel(channel)
    await sb.auth.signOut()
}

main().catch(console.error)