supabase-postgres-best-practices

SKILL.md

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.

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

Priority
Category
Impact
Prefix

1
Query Performance
CRITICAL
query-

2
Connection Management
CRITICAL
conn-

3
Security & RLS
CRITICAL
security-

4
Schema Design
HIGH
schema-

5
Concurrency & Locking
MEDIUM-HIGH
lock-

6
Data Access Patterns
MEDIUM
data-

7
Monitoring & Diagnostics
LOW-MEDIUM
monitor-

8
Advanced Features
LOW
advanced-

How to Use

Read individual rule files for detailed explanations and SQL examples:

references/query-missing-indexes.md
references/query-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)

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