Supabase -- Backend Integration Expert

---

name: supabase description: > Build Supabase auth flows, RLS policies, real-time subscriptions, Edge Functions, and migrations. USE WHEN: User needs Supabase auth, real-time, Row Level Security, Edge Functions, database setup, or migrations. DON'T USE WHEN: User needs general database optimization. Use Cortex for analytics queries. OUTPUTS: Auth configurations, RLS policies, real-time setups, Edge Functions, migration files, type-safe query patterns. version: 1.1.0 author: SpookyJuice tags: [supabase, postgres, auth, realtime, edge-functions] price: 14 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1" content_hash: "sha256:b9009e44a01dd7e7ad04389640298838a0730500a92fe618a2f62ba40f5b9810"

#‍​‌‌​‌‌‌‌​‌‌‌​​‌‌​‌‌‌​​​​​‌‌‌​​‌‌​​‌‌‌​‌​​​‌‌​​​‌​​‌‌‌​‌​​‌‌‌​​‌‌​‌‌​‌​‌​​​‌​‌‌​‌​​‌‌‌​​​​​‌‌​​​​​​‌‌​‌‌‌​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌‌​​‌‌​​‌‌​‌‌​​​‌‌‍ Supabase

Version: 1.1.0 Price: $14 Type: Skill

Description

Production-grade Supabase integration patterns for the cross-service interactions that stall projects. Supabase bundles Postgres, Auth, Realtime, Storage, and Edge Functions behind a clean API, but the integration points between these services — RLS policies that block your own auth flow, real-time subscriptions that silently drop, migrations that lock tables in production — are where projects stall. This skill encodes the cross-service patterns and failure modes.

Prerequisites

• Supabase project (free tier works for development)
• Supabase CLI: brew install supabase/tap/supabase
• SUPABASE_URL and SUPABASE_ANON_KEY (from project settings)
• SUPABASE_SERVICE_ROLE_KEY for server-side operations
• For Edge Functions: Deno installed locally

Setup

1. Copy SKILL.md into your OpenClaw skills directory
2. Set environment variables:

   export SUPABASE_URL="https://your-project.supabase.co"
   export SUPABASE_ANON_KEY="eyJ..."
   export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
   

3. Reload OpenClaw

Commands

• "Set up auth with [email/OAuth/magic link]"
• "Write RLS policies for [table/access pattern]"
• "Configure real-time for [table/channel]"
• "Create an Edge Function for [purpose]"
• "Generate a migration for [schema change]"
• "Set up type-safe queries for [table]"
• "Debug my RLS — queries return empty"

Workflow

Auth Implementation

1. Provider configuration — enable providers in the Supabase dashboard: email/password, magic link, Google, GitHub, etc. For OAuth, configure redirect URLs (don't forget localhost for dev AND your production domain).
2. Client-side auth — implement sign-up, sign-in, sign-out, and password reset using @supabase/supabase-js. Handle the auth state change listener (onAuthStateChange) to update UI and manage sessions.
3. Session management — the client library handles token refresh automatically BUT only if the client instance is persistent. If you create a new client per request (common in SSR), implement explicit token refresh.
4. Server-side verification — on your API routes/server: verify the JWT from the Authorization header using the service_role key. Never trust the anon key for server-side operations — it only enforces RLS.
5. Redirect handling — OAuth and magic link flows redirect back to your app with tokens in the URL fragment. Use supabase.auth.getSession() on the callback page to exchange the URL tokens for a proper session.
6. Profile creation — set up a database trigger or use the auth.users table with RLS to create a public profiles table that syncs with auth. This separates auth data from application data.

Row Level Security

1. Enable RLS — ALTER TABLE your_table ENABLE ROW LEVEL SECURITY; — this blocks ALL access by default, including from your application. This is the correct starting point.
2. Policy design — for each table, define policies for: SELECT (who can read), INSERT (who can create), UPDATE (who can modify), DELETE (who can remove). Use auth.uid() to reference the authenticated user.
3. Common patterns — implement the standard patterns:
   • Own data: USING (auth.uid() = user_id) — users see only their own rows
   • Team data: USING (auth.uid() IN (SELECT user_id FROM team_members WHERE team_id = your_table.team_id)) — team members see team data
   • Public read, private write: SELECT policy with USING (true), INSERT/UPDATE/DELETE policies with USING (auth.uid() = user_id)
   • Role-based: USING (auth.uid() IN (SELECT user_id FROM roles WHERE role = 'admin')) — admin-only access
4. WITH CHECK clauses — USING controls which rows are visible; WITH CHECK controls which rows can be inserted/updated. They're different. For INSERT, you need WITH CHECK, not USING.
5. Testing — test every policy by: querying as an unauthenticated user (should fail), querying as the wrong user (should return empty or fail), and querying as the correct user (should succeed). Use the SQL editor with SET request.jwt.claims to simulate different users.
6. Service role bypass — the service_role key bypasses RLS entirely. Use it only on your server, never on the client. This is your escape hatch for admin operations and migrations.

Real-Time Subscriptions

1. Channel setup — choose the subscription type: Postgres Changes (reacts to database INSERT/UPDATE/DELETE), Broadcast (pub/sub messaging), or Presence (track who's online).
2. Postgres Changes — subscribe to table changes with filter: supabase.channel('changes').on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages', filter: 'room_id=eq.123' }, callback). RLS policies apply to real-time too.
3. Connection lifecycle — subscribe on mount, unsubscribe on unmount. Handle reconnection: the client library reconnects automatically but you should re-fetch data on reconnect to catch events missed during disconnection.
4. Memory management — unsubscribe from channels when components unmount. Zombie subscriptions leak memory and can cause unexpected behavior. Use supabase.removeChannel(channel).
5. Presence — track online users with channel.track({ user_id, online_at }). Handle sync, join, and leave events. Presence state is eventually consistent — don't use it for critical data.
6. Scaling considerations — Supabase has concurrent connection limits per tier. For high-traffic apps, use Broadcast channels (lightweight) instead of Postgres Changes (heavier) where possible.

Output Format

⚡ SUPABASE — [IMPLEMENTATION TYPE]
Project: [Name]
Feature: [Auth/RLS/Realtime/Edge Functions/Migrations]
Date: [YYYY-MM-DD]

═══ CONFIGURATION ═══
[Environment variables and dashboard settings]

═══ IMPLEMENTATION ═══
[Code with inline comments]

═══ RLS POLICIES ═══
| Table | Operation | Policy | Rule |
|-------|-----------|--------|------|
| [table] | SELECT | [name] | [USING clause] |

═══ MIGRATION ═══
[SQL migration file content]

═══ TESTING ═══
☐ [Test case: auth flow works for each provider]
☐ [Test case: RLS blocks unauthorized access]
☐ [Test case: real-time receives updates]

Common Pitfalls

• RLS blocks your own app — enabling RLS blocks ALL access by default, including your application using the anon key. You must create explicit policies. Empty query results usually mean missing RLS policies, not empty tables.
• Forgetting WITH CHECK on INSERT — USING only applies to SELECT/UPDATE/DELETE. For INSERT policies, you need WITH CHECK. Without it, inserts fail silently.
• Real-time and RLS interaction — Postgres Changes subscriptions are filtered by RLS policies. If a user can't SELECT a row, they won't receive real-time updates for it. This is correct but surprising.
• Service role key on the client — never expose the service_role key in client-side code. It bypasses all RLS. Use the anon key for clients, service_role only on your server.
• Migration ordering — run migrations with supabase db push for development, supabase migration for production. Never modify production directly through the dashboard — it creates drift.

Guardrails

• Never exposes service role key. The service_role key is server-only. Any implementation that puts it in client-side code is immediately flagged and corrected.
• RLS by default. Every new table gets RLS enabled. Tables without RLS are explicitly flagged as a security risk.
• Migrations are versioned. Schema changes go through migration files, not dashboard clicks. Reproducible, reviewable, and rollback-able.
• Connection cleanup. Every real-time subscription includes cleanup code. No zombie connections, no memory leaks.
• Test every policy. RLS policies are tested with authenticated, unauthenticated, and wrong-user queries before deployment.
• Cost awareness. Flags when approaching tier limits: database size, bandwidth, Edge Function invocations, and real-time connections.
• Backup verified before destructive migrations. Every migration that drops tables, columns, or alters data types requires a confirmed backup before execution. No irreversible schema changes without a rollback path.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice — https://www.shopclawmart.com