feat: supabase db references

[Rodriguespn]

What kind of change does this PR introduce?

New skill references for Supabase database management and best practices.

What is the current behavior?

No existing reference files for database-specific topics in the Supabase skill. The skill structure and build system were recently established, but database references had not yet been implemented.

What is the new behavior?

Comprehensive database guidance organized into six focused categories covering the most critical aspects of working with Supabase's PostgreSQL database.

Reference Structure

The database references are organized into six categories: Row Level Security (RLS), Connection Pooling, Schema Design, Migrations, Performance, and Security.

• Row Level Security (RLS)

  • Covers policy patterns, common mistakes, and performance tuning
  • Emphasizes importance of correct RLS configuration in Supabase
  • Includes PERMISSIVE vs RESTRICTIVE policies, mandatory RLS, views, and pitfalls

• Connection Pooling

  • Focuses on Supavisor pooling modes
  • Explains Transaction mode (port 6543) vs Session mode (port 5432)
  • Highlights risks of connection exhaustion and prepared statement incompatibilities

• Schema Design

  • Supabase-specific design patterns
  • auth.users foreign keys with CASCADE
  • Best practices for timestamptz, JSONB + indexing, PostgreSQL extensions, and Realtime
  • Prevents orphaned records and improves Supabase integration

• Migrations

  • Using Supabase CLI for schema changes
  • Idempotent migration patterns
  • Local testing with supabase db reset
  • Generating migrations with supabase db diff

• Performance

  • Index selection guidance (B-tree, BRIN, GIN, partial)
  • Query optimization for PostgREST
  • Notes potential 10–1000x performance improvements with proper indexing

• Security

  • Service role key handling (bypasses all RLS)
  • Warning to never expose service role key to browsers
  • Use of security definer functions in private schemas for elevated operations

Key Topics Covered

• RLS mandatory enablement: Preventing unauthorized data access by enabling RLS on all exposed tables
• Connection pooling modes: Transaction vs Session mode selection for serverless vs long-running applications
• auth.users CASCADE constraints: Preventing orphaned records and user deletion failures
• Idempotent migrations: Writing safe migrations with IF NOT EXISTS/IF EXISTS patterns
• Index type selection: Choosing between B-tree, BRIN, GIN, and partial indexes based on query patterns
• Service role key security: Preventing complete database compromise by never exposing the service_role key to browsers
• RLS policy types: Using PERMISSIVE (OR logic) vs RESTRICTIVE (AND logic) policies correctly
• Timestamp patterns: Using timestamptz for consistency with Supabase Auth
• JSONB optimization: Proper indexing strategies for JSON columns with GIN indexes
• Migration testing: Local validation workflows with supabase db reset before production deployment
• Security definer functions: Implementing elevated operations safely with proper search_path configuration

Sources

Documentation and references consulted:

• Supabase Database documentation (https://supabase.com/docs/guides/database)
• Supabase Postgres documentation (https://supabase.com/docs/guides/database/postgres)
• Row Level Security guide (https://supabase.com/docs/guides/database/postgres/row-level-security)
• Connection pooling documentation (https://supabase.com/docs/guides/database/connecting-to-postgres)
• Supabase CLI reference (https://supabase.com/docs/reference/cli)
• Local development guide (https://supabase.com/docs/guides/local-development)
• API Keys documentation (https://supabase.com/docs/guides/api/api-keys)
• PostgreSQL documentation for index types and performance optimization

Design Decisions

• Common mistakes emphasis: Each reference file uses an "Incorrect/Correct" pattern showing anti-patterns first, then the proper solution. This pattern was chosen because agents frequently need to help users debug existing code, and seeing common mistakes helps them identify issues faster. The incorrect examples are concrete and represent real production issues observed in Supabase projects.

• Supabase-specific focus: Intentionally excluded generic PostgreSQL guidance that Claude already knows (like basic SELECT queries or standard table creation). Instead, focused exclusively on Supabase-specific patterns like auth.uid() usage, Supavisor configuration, and Supabase CLI workflows. This maximizes the value-per-token of each reference.