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)

Quick Decision Tree

Problem?
├─ Slow query → query-missing-indexes, query-composite-indexes, monitor-explain-analyze
├─ Connection errors / timeouts → conn-pooling, conn-limits, conn-idle-timeout
├─ Deadlocks / long transactions → lock-short-transactions, lock-deadlock-prevention
├─ Bulk load slow → data-batch-inserts, data-upsert
├─ Table bloat / VACUUM issues → monitor-vacuum-analyze
├─ JSONB queries slow → advanced-jsonb-indexing
├─ FTS / search quality → advanced-full-text-search (pair with /postgres-semantic-search for BM25 + vector)
└─ Security / multi-tenant → security-* rules, RLS

Related Skills

/postgres-semantic-search — Vector search (pgvector), hybrid BM25 + semantic, ParadeDB
/nextjs-chatbot — Chatbot orchestration, session DB, feedback, HITL
/ai-sdk-6 — AI SDK v6 patterns for backend integration

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/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)