Supabase Row Level Security: Beginner's Guide 2026

Master Supabase RLS policies with production patterns. Real errors, exact code, and critical gotchas every indie hacker needs.

TL;DR

Supabase Row Level Security (RLS) enforces data access at the database level using PostgreSQL policies. Enable it per table, write policies matching your auth scheme, and test with service role keys vs. authenticated tokens. Most beginners skip the USING clause or forget auth.uid() context—both cause silent failures.

---

What is Row Level Security?

RLS is a PostgreSQL feature that Supabase exposes through its dashboard and client libraries. Instead of filtering data in your application code (vulnerable to logic errors), you define rules at the database layer:

Without RLS, any user with your anon key can query any row. With RLS enabled, PostgreSQL enforces policies before returning results.

---

Enable RLS on a Table

```sql ALTER TABLE profiles ENABLE ROW LEVEL SECURITY; ```

That's it. Now:

Critical: Enable RLS *before* adding policies, or your app breaks immediately.

---

Core RLS Concepts

The Authentication Context

Every request includes metadata:

```sql auth.uid() -- Current user's UUID auth.jwt() -- Full JWT claims object auth.role() -- 'authenticated' or 'anon' current_setting('request.jwt.claims') -- Raw claims ```

You reference these in policies:

```sql SELECT * FROM profiles WHERE id = auth.uid(); -- Only see your own row ```

Policy Structure

Each policy has:

---

Real-World Patterns

Pattern 1: User Owns Their Profile

```sql CREATE POLICY "Users can view own profile" ON profiles FOR SELECT USING (auth.uid() = id);

CREATE POLICY "Users can update own profile" ON profiles FOR UPDATE USING (auth.uid() = id) WITH CHECK (auth.uid() = id); ```

The WITH CHECK prevents users from changing id to someone else's UUID.

Pattern 2: Public Read, Authenticated Write

```sql CREATE POLICY "Anyone can read posts" ON posts FOR SELECT USING (true);

CREATE POLICY "Users can insert own posts" ON posts FOR INSERT WITH CHECK (auth.uid() = author_id); ```

Pattern 3: Admin Override

```sql CREATE POLICY "Admins see everything" ON posts FOR ALL USING ( auth.uid() IN ( SELECT id FROM profiles WHERE role = 'admin' ) ); ```

Warning: This policy queries another table on every request. Cache admin IDs in a custom claim instead ([authentication patterns](/?guide=supabase-auth)).

Pattern 4: Team-Based Access

```sql CREATE POLICY "Users access their team's projects" ON projects FOR SELECT USING ( team_id IN ( SELECT team_id FROM team_members WHERE user_id = auth.uid() ) ); ```

---

Common Errors & Solutions

Error 1: Policy Returns No Rows

``` ERROR: new row violates row-level security policy for table "profiles" DETAIL: Failing row contains (550e8400-e29b-41d4-a716-446655440000, john@example.com, ...). ```

Cause: WITH CHECK clause rejected the insert. Usually:

Fix: Verify field names and order of comparisons.

```javascript const { error } = await supabase .from('profiles') .insert({ id: auth.uid(), email: 'user@example.com' }); // id must match auth.uid() ```

Error 2: Permission Denied

``` ERROR: permission denied for schema public ```

Cause: Using anon key on a table with no SELECT policy.

Fix: Add a policy or use service role key (only in backend).

Error 3: Silent Empty Results

```javascript const { data } = await supabase .from('posts') .select(); // Returns [] even though posts exist ```

Cause: Missing SELECT policy. No error thrown—just empty results. This is the worst one because it "works" locally with service role.

Fix: Always test with anon key in dev.

---

Testing RLS Properly

Wrong Approach (Local Development)

```javascript const supabase = createClient(url, SERVICE_ROLE_KEY); // Service role BYPASSES RLS—tests pass but production fails ```

Right Approach

```javascript // Test as anonymous user const anonClient = createClient(url, ANON_KEY); const { data: anonPosts } = await anonClient .from('posts') .select();

// Test as authenticated user const authClient = createClient(url, ANON_KEY); await authClient.auth.signInWithPassword({ email, password }); const { data: authPosts } = await authClient .from('posts') .select(); ```

Supabase version: These patterns work on v1.51+. [Verify in official docs](https://supabase.com/docs/guides/auth/row-level-security).

---

Performance Considerations

Avoid This

```sql -- Queries team_members table on EVERY request CREATE POLICY "Access team data" ON documents FOR SELECT USING ( team_id IN ( SELECT team_id FROM team_members WHERE user_id = auth.uid() ) ); ```

Do This Instead

Store team info in JWT custom claims:

```sql CREATE POLICY "Access team data" ON documents FOR SELECT USING ( team_id = (auth.jwt() ->> 'team_id')::uuid ); ```

Update claims during login (in your backend).

---

Quick Checklist

---

Resources

---

What am I missing?

Comments below: Did I gloss over a critical error you've hit? Better patterns for team access? Gotchas with real-time subscriptions and RLS? I'm reading every response.