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

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