supabase-postgres-best-practices
About supabase-postgres-best-practices
Supabase Postgres Best Practices is a reference skill maintained by Supabase for query optimization and database design. Its prioritized rules cover performance, connections, security, schema, and other Postgres concerns, with SQL examples for individual recommendations.
Key features
- 01Eight categories of Postgres guidance
- 02Rules prioritized by impact
- 03SQL examples for each rule
- 04Coverage of RLS and connection pooling
- 05Diagnostics for queries and vacuuming
Use cases
- 01Optimizing slow SQL queries
- 02Designing indexes and schemas
- 03Reviewing RLS and database security
- 04Troubleshooting connection or vacuum issues
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/supabase-postgres-best-practicesin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
CHANGELOG.mdreferences/_contributing.md_sections.md_template.mdadvanced-full-text-search.mdadvanced-jsonb-indexing.mdconn-idle-timeout.mdconn-limits.mdconn-pooling.mdconn-prepared-statements.mddata-batch-inserts.mddata-n-plus-one.mddata-pagination.mddata-upsert.mdlock-advisory.mdlock-deadlock-prevention.mdlock-short-transactions.mdlock-skip-locked.mdmonitor-explain-analyze.mdmonitor-pg-stat-statements.mdmonitor-vacuum-analyze.mdquery-composite-indexes.mdquery-covering-indexes.mdquery-index-types.mdquery-missing-indexes.mdquery-partial-indexes.mdschema-constraints.mdschema-data-types.mdschema-foreign-key-indexes.mdschema-lowercase-identifiers.mdDetails
From the project READMESupabase 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— AI SDK 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/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)