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