---
name: supabase-best-practices
description: Supabase security and performance guidelines with Clerk authentication integration. Contains 40+ rules across 10 categories covering RLS policies, Clerk setup, database security, and more.
license: MIT
metadata:
  author: AI Engineering Team
  version: "1.0.1"
  last_updated: "2025-01-27"
---

# Supabase Best Practices

Comprehensive security and performance optimization guide for Supabase applications with Clerk authentication integration. Contains 40+ rules across 10 categories, prioritized by impact to guide secure development and code review.

## When to Apply

Reference these guidelines when:
- Setting up a new Supabase project
- Integrating Clerk authentication with Supabase
- Writing Row Level Security (RLS) policies
- Designing database schemas
- Implementing real-time features
- Configuring Storage buckets
- Writing Edge Functions
- Reviewing code for security issues

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Row Level Security | CRITICAL | `rls-` |
| 2 | Clerk Integration | CRITICAL | `clerk-` |
| 3 | Database Security | HIGH | `db-` |
| 4 | Authentication Patterns | HIGH | `auth-` |
| 5 | API Security | HIGH | `api-` |
| 6 | Storage Security | MEDIUM-HIGH | `storage-` |
| 7 | Realtime Security | MEDIUM | `realtime-` |
| 8 | Edge Functions | MEDIUM | `edge-` |
| 9 | Testing | MEDIUM | `test-` |
| 10 | Security | MEDIUM | `security-` |

## Quick Reference

### 1. Row Level Security (CRITICAL)

- `rls-always-enable` - Always enable RLS on public schema tables
- `rls-wrap-functions-select` - Wrap auth functions with (SELECT ...) for performance
- `rls-add-indexes` - Add indexes on columns used in RLS policies
- `rls-specify-roles` - Specify roles with TO authenticated clause
- `rls-security-definer` - Use SECURITY DEFINER functions for complex policies
- `rls-minimize-joins` - Minimize joins in RLS policies
- `rls-explicit-auth-check` - Use explicit auth.uid() checks
- `rls-restrictive-policies` - Use RESTRICTIVE policies for additional constraints

### 2. Clerk Integration (CRITICAL)

- `clerk-setup-third-party` - Use Third-Party Auth integration (not JWT templates)
- `clerk-client-server-side` - Use accessToken callback for server-side clients
- `clerk-client-client-side` - Use useSession() hook for client-side clients
- `clerk-role-claim` - Configure role: authenticated claim in Clerk
- `clerk-org-policies` - Use organization claims for multi-tenant RLS
- `clerk-mfa-policies` - Enforce MFA with RESTRICTIVE policies
- `clerk-no-jwt-templates` - Never use deprecated JWT template integration

### 3. Database Security (HIGH)

- `db-migrations-versioned` - Use versioned migrations for schema changes
- `db-schema-design` - Follow proper schema design patterns
- `db-indexes-strategy` - Implement proper indexing strategy
- `db-foreign-keys` - Always use foreign key constraints
- `db-triggers-security` - Secure trigger functions properly
- `db-views-security-invoker` - Use SECURITY INVOKER for views

### 4. Authentication Patterns (HIGH)

- `auth-jwt-claims-validation` - Always validate JWT claims
- `auth-user-metadata-safety` - Treat user_metadata as untrusted
- `auth-app-metadata-authorization` - Use app_metadata for authorization
- `auth-session-management` - Implement proper session management

### 5. API Security (HIGH)

- `api-filter-queries` - Always filter queries even with RLS
- `api-publishable-keys` - Use publishable keys correctly
- `api-service-role-server-only` - Never expose service role key to client

### 6. Storage Security (MEDIUM-HIGH)

- `storage-rls-policies` - Enable RLS on storage.objects
- `storage-bucket-security` - Configure bucket-level security
- `storage-signed-urls` - Use signed URLs for private files

### 7. Realtime Security (MEDIUM)

- `realtime-private-channels` - Use private channels for sensitive data
- `realtime-rls-authorization` - RLS policies apply to realtime
- `realtime-cleanup-subscriptions` - Clean up subscriptions on unmount

### 8. Edge Functions (MEDIUM)

- `edge-verify-jwt` - Always verify JWT in edge functions
- `edge-cors-handling` - Handle CORS properly
- `edge-secrets-management` - Use secrets for sensitive data

### 9. Testing (MEDIUM)

- `test-pgtap-rls` - Test RLS policies with pgTAP
- `test-isolation` - Isolate tests properly
- `test-helpers` - Use test helper functions

### 10. Security (MEDIUM)

- `security-validate-inputs` - Validate all inputs before processing
- `security-audit-advisors` - Regularly run Security Advisor checks

## How to Use

Read individual rule files for detailed explanations and code examples:

```
references/rules/rls-always-enable.md
references/rules/clerk-setup-third-party.md
references/rules/_sections.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- When NOT to use the pattern
- Reference links to official documentation

## Full Compiled Document

For the complete guide with all rules expanded: `references/supabase-guidelines.md`