supabase-sdk-patterns

•

2k2653 months ago

Execute apply production-ready Supabase SDK patterns for TypeScript and Python. Use when implementing Supabase integrations, refactoring SDK usage, or establishing team coding standards for Supabase. Trigger with phrases like "supabase SDK patterns", "supabase best practices", "supabase code patterns", "idiomatic supabase".

Quick Install

npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill supabase-sdk-patterns

Instructions

Supabase SDK Patterns

Overview

Production patterns for @supabase/supabase-js v2 and supabase-py. Every Supabase query returns { data, error } — never assume success. This skill covers client initialization, CRUD with filters, auth, realtime subscriptions, storage, RPC, and the Python equivalent for each pattern.

Prerequisites

Supabase project with URL and anon key (or service role key for server-side)
@supabase/supabase-js v2 installed (TypeScript) or supabase pip package (Python)
TypeScript projects: generated database types via supabase gen types typescript

Instructions

Step 1: Initialize a Typed Singleton Client

Create one client instance and reuse it. Never call createClient per-request.

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885

Tags & Topics

aiautomationclaude-codedevopsmcpai-agents

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

let supabase: ReturnType<typeof createClient<Database>>

export function getSupabase() {
  if (!supabase) {
    supabase = createClient<Database>(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_ANON_KEY!,
      {
        auth: { autoRefreshToken: true, persistSession: true },
        db: { schema: 'public' },
        global: { headers: { 'x-app-name': 'my-app' } },
      }
    )
  }
  return supabase
}

from supabase import create_client, Client

_client: Client | None = None

def get_supabase() -> Client:
    global _client
    if _client is None:
        _client = create_client(
            os.environ["SUPABASE_URL"],
            os.environ["SUPABASE_ANON_KEY"],
        )
    return _client

const { data, error } = await getSupabase()
  .from('users')
  .select('id, name, email')
  .eq('active', true)       // WHERE active = true
  .gt('age', 18)            // AND age > 18
  .ilike('name', '%john%')  // AND name ILIKE '%john%'
  .in('role', ['admin', 'editor'])  // AND role IN (...)
  .order('name', { ascending: true })
  .limit(10)

if (error) throw error
// data is typed as Pick<User, 'id' | 'name' | 'email'>[]

const { data: newUser, error } = await getSupabase()
  .from('users')
  .insert({ name: 'Alice', email: '[email protected]', active: true })
  .select()       // Without .select(), data is null
  .single()       // Unwrap from array to single object

if (error) throw error
// newUser is the full row with server-generated id, created_at, etc.

const { data, error } = await getSupabase()
  .from('users')
  .upsert(
    { email: '[email protected]', name: 'Alice Updated' },
    { onConflict: 'email' }   // Match on unique column
  )
  .select()
  .single()

// Update
const { data, error } = await getSupabase()
  .from('users')
  .update({ active: false })
  .eq('id', userId)
  .select()
  .single()

// Delete
const { error } = await getSupabase()
  .from('users')
  .delete()
  .eq('id', userId)

const { data, error } = await getSupabase()
  .rpc('my_function', { arg1: 'value', arg2: 42 })

if (error) throw error
// data is the function's return value

Filter	SQL Equivalent	Example
`.eq(col, val)`	`= val`	`.eq('status', 'active')`
`.neq(col, val)`	`!= val`	`.neq('role', 'guest')`
`.gt(col, val)`	`> val`	`.gt('age', 18)`
`.gte(col, val)`	`>= val`	`.gte('score', 90)`
`.lt(col, val)`	`< val`	`.lt('price', 100)`
`.lte(col, val)`	`<= val`	`.lte('quantity', 0)`
`.like(col, pat)`	`LIKE pat`	`.like('name', '%son')`
`.ilike(col, pat)`	`ILIKE pat`	`.ilike('email', '%@gmail%')`
`.is(col, val)`	`IS val`	`.is('deleted_at', null)`
`.in(col, arr)`	`IN (...)`	`.in('id', [1, 2, 3])`
`.contains(col, val)`	`@> val`	`.contains('tags', ['urgent'])`
`.range(from, to)`	`OFFSET/LIMIT`	`.range(0, 9)` (first 10 rows)

# Select with filters
result = get_supabase() \
    .table('users') \
    .select('id, name, email') \
    .eq('active', True) \
    .gt('age', 18) \
    .order('name') \
    .limit(10) \
    .execute()

if result.data is None:
    raise Exception(f"Query failed")

# Insert
result = get_supabase().table('users').insert({
    "name": "Alice", "email": "[email protected]"
}).execute()

# Upsert
result = get_supabase().table('users').upsert({
    "email": "[email protected]", "name": "Alice Updated"
}).execute()

# RPC
result = get_supabase().rpc('my_function', {"arg1": "value"}).execute()

// Sign up
const { data, error } = await getSupabase().auth.signUp({
  email: '[email protected]',
  password: 'securepassword',
})

// Sign in with password
const { data, error } = await getSupabase().auth.signInWithPassword({
  email: '[email protected]',
  password: 'securepassword',
})
// data.session contains access_token, refresh_token
// data.user contains user metadata

// Get current session
const { data: { session } } = await getSupabase().auth.getSession()
if (!session) {
  // User is not authenticated
}

// Sign out
await getSupabase().auth.signOut()

// Listen for auth changes
getSupabase().auth.onAuthStateChange((event, session) => {
  // event: 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | ...
  console.log('Auth event:', event, session?.user?.email)
})

const channel = getSupabase()
  .channel('room-messages')
  .on(
    'postgres_changes',
    {
      event: '*',           // 'INSERT' | 'UPDATE' | 'DELETE' | '*'
      schema: 'public',
      table: 'messages',
      filter: 'room_id=eq.42',  // Optional row-level filter
    },
    (payload) => {
      console.log('Change:', payload.eventType, payload.new)
      // payload.new = the new row (INSERT/UPDATE)
      // payload.old = the old row (UPDATE/DELETE)
    }
  )
  .subscribe((status) => {
    // status: 'SUBSCRIBED' | 'CLOSED' | 'CHANNEL_ERROR'
    console.log('Subscription status:', status)
  })

// Clean up when done
await getSupabase().removeChannel(channel)

// Upload a file
const { data, error } = await getSupabase().storage
  .from('avatars')          // bucket name
  .upload('users/avatar.png', file, {
    cacheControl: '3600',
    upsert: true,           // overwrite if exists
    contentType: 'image/png',
  })

// Download a file
const { data, error } = await getSupabase().storage
  .from('avatars')
  .download('users/avatar.png')
// data is a Blob

// Get public URL (no auth required if bucket is public)
const { data: { publicUrl } } = getSupabase().storage
  .from('avatars')
  .getPublicUrl('users/avatar.png')

// Get signed URL (time-limited access for private buckets)
const { data, error } = await getSupabase().storage
  .from('documents')
  .createSignedUrl('reports/q4.pdf', 3600)  // expires in 1 hour
// data.signedUrl

const { data, error } = await getSupabase().from('users').select('*')

if (error) {
  // error is a PostgrestError with these fields:
  //   error.message  — human-readable description
  //   error.code     — Postgres error code (e.g., '23505')
  //   error.details  — additional context
  //   error.hint     — suggested fix from Postgres
  console.error(`Query failed [${error.code}]: ${error.message}`)
  throw error
}

// Only safe to use data after error check

Error Code	Meaning	What to Do
`PGRST116`	No rows found (`.single()`)	Return null or 404, don't throw
`23505`	Unique constraint violation	Use `.upsert()` or show conflict error
`42501`	RLS policy violation	Check auth state and RLS policies
`PGRST000`	Connection error	Retry with exponential backoff
`42P01`	Table does not exist	Verify table name and run migrations
`23503`	Foreign key violation	Ensure referenced row exists first
`42703`	Column does not exist	Check column name, regenerate types

// services/user-service.ts
import type { Database } from '../lib/database.types'

type User = Database['public']['Tables']['users']['Row']
type UserInsert = Database['public']['Tables']['users']['Insert']

export const UserService = {
  async getById(id: string): Promise<User | null> {
    const { data, error } = await getSupabase()
      .from('users')
      .select('*')
      .eq('id', id)
      .single()

    if (error?.code === 'PGRST116') return null  // Not found
    if (error) throw error
    return data
  },

  async search(query: string, limit = 20): Promise<User[]> {
    const { data, error } = await getSupabase()
      .from('users')
      .select('id, name, email, avatar_url')
      .or(`name.ilike.%${query}%,email.ilike.%${query}%`)
      .order('name')
      .limit(limit)

    if (error) throw error
    return data
  },

  async createOrUpdate(user: UserInsert): Promise<User> {
    const { data, error } = await getSupabase()
      .from('users')
      .upsert(user, { onConflict: 'email' })
      .select()
      .single()

    if (error) throw error
    return data
  },
}

async function paginate<T>(
  table: string,
  select: string,
  { page = 1, pageSize = 20, orderBy = 'id' } = {}
) {
  const from = (page - 1) * pageSize
  const to = from + pageSize - 1

  const { data, error, count } = await getSupabase()
    .from(table)
    .select(select, { count: 'exact' })
    .order(orderBy)
    .range(from, to)

  if (error) throw error
  return {
    data: data as T[],
    page,
    pageSize,
    total: count ?? 0,
    totalPages: Math.ceil((count ?? 0) / pageSize),
  }
}

// Usage
const result = await paginate<User>('users', 'id, name, email', { page: 2 })

supabase-sdk-patterns

Supabase SDK Patterns

Overview

Prerequisites

Instructions

Step 1: Initialize a Typed Singleton Client

Related Skills

skill-creator

skill-creator

1password

himalaya

skill-creator

skill-creator

1password

himalaya

Supabase SDK Patterns

Overview

Prerequisites

Instructions

Step 1: Initialize a Typed Singleton Client

Step 2: Query, Filter, and Mutate Data

Step 3: Auth, Realtime, and Storage

Output

Error Handling

Examples

Resources

Next Steps

Related Skills

skill-creator

skill-creator

1password

himalaya

Related Skills

skill-creator

skill-creator

1password

himalaya