supabase-known-pitfalls

name	supabase-known-pitfalls
description	Use when reviewing Supabase code, onboarding developers, auditing an existing project, or debugging unexpected behavior — catches the twelve most common Supabase mistakes: exposing the service_role key in client bundles, forgetting to enable RLS, skipping connection pooling in serverless, .single() throwing on empty results, missing .select() after insert/update, ignoring { data, error }, creating multiple client instances, and not using generated types. Trigger with phrases like "supabase mistakes", "supabase anti-patterns", "supabase pitfalls", "supabase code review", "supabase gotchas", "supabase debugging", "what not to do supabase", "supabase common errors".
allowed-tools	Read, Grep
version	1.53.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","supabase","anti-patterns","code-review","debugging","security","pitfalls"]
compatibility	Designed for Claude Code

Supabase Known Pitfalls

Overview

The twelve most common Supabase mistakes, ranked by severity: security (service_role exposure, missing RLS, permissive policies, no connection pooling), data integrity (ignoring { data, error }, missing .select() after mutations, .single() on optional results), and performance / maintainability (select('*'), N+1 queries, missing FK indexes, multiple client instances, no generated types). Each pitfall shows the broken code, why it fails, and the correct pattern using createClient from @supabase/supabase-js.

This SKILL.md carries the full pitfall table plus one representative fix per category. The verbatim broken-vs-correct code and detection queries for all twelve live in references/pitfalls.md — drill in there for depth.

Prerequisites

• Access to a Supabase project codebase for review
• @supabase/supabase-js v2+ installed
• Basic understanding of Row Level Security (RLS)

Instructions

Work the pitfalls top-down by severity. Fix every Critical finding before moving on — a single security miss can expose the whole database.

#	Pitfall	Severity	Fix
1	service_role key in client bundle	Critical	anon key on client; service_role server-only, no NEXT_PUBLIC_
2	Table without RLS	Critical	ALTER TABLE … ENABLE ROW LEVEL SECURITY right after CREATE TABLE
3	Overly permissive RLS policy	Critical	scope USING (…) to auth.uid(), never USING (true) for writes
4	No connection pooling in serverless	Critical	pooled string (Supavisor, port 6543), not the direct 5432 URL
5	Ignoring { data, error }