Supabase Postgres Best Practices

Supabase Postgres Best Practices

Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.

Triggers

• supabase
• postgres
• postgresql
• sql
• database query
• rls
• row level security
• realtime
• supabase auth
• pg
• query optimization

When to Apply

Reference these guidelines when:

• Writing SQL queries or designing schemas
• Implementing indexes or query optimization
• Reviewing database performance issues
• Configuring connection pooling or scaling
• Optimizing for Postgres-specific features
• Working with Row-Level Security (RLS)

Rule Categories by Priority

How to Use

Read individual rule files for detailed explanations and SQL examples:

references/query-missing-indexes.md
references/schema-partial-indexes.md
references/_sections.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect SQL example with explanation
• Correct SQL example with explanation
• Optional EXPLAIN output or metrics
• Additional context and references
• Supabase-specific notes (when applicable)

Verify

• The code was actually executed (or type-checked / linted as appropriate) and the command output is captured
• Dependencies and runtime versions used are pinned and recorded (e.g., requirements.txt, package.json + lockfile, .nvmrc)
• Errors or warnings emitted by the run are addressed or explicitly accepted with a reason
• New external I/O (network, filesystem, DB) has timeouts and error handling, not silent failure
• Tests for the change were run and the pass/fail count is in the transcript
• Secrets and credentials are read from env/secret store, not hard-coded, and .env files are not committed

References

• https://www.postgresql.org/docs/current/
• https://supabase.com/docs
• https://wiki.postgresql.org/wiki/Performance_Optimization
• https://supabase.com/docs/guides/database/overview
• https://supabase.com/docs/guides/auth/row-level-security