Supabase Best Practices

When to Apply

• 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

rls-

clerk-

db-

auth-

api-

storage-

realtime-

edge-

test-

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

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

• 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

references/supabase-guidelines.md