supabase-postgres-best-practices
supabase/agent-skills
Postgres performance optimization and best practices guide from Supabase for query, schema, and configuration tuning.
What is supabase-postgres-best-practices?
Comprehensive reference for optimizing Postgres databases with rules across 8 priority categories: query performance, connection management, security, schema design, concurrency, data access, monitoring, and advanced features. Use when writing queries, designing schemas, reviewing performance issues, or configuring database scaling.
- Provides 8 categories of optimization rules prioritized by performance impact
- Includes detailed SQL examples showing incorrect vs. correct patterns
- Offers EXPLAIN output and performance metrics for query analysis
- Covers query performance, indexing, connection pooling, and RLS configuration
- Guides schema design and concurrency optimization
- Provides monitoring and diagnostics recommendations
How to install supabase-postgres-best-practices
npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practicesHow to use supabase-postgres-best-practices
- 1.Identify which rule category applies to your task (query performance, schema design, security, etc.)
- 2.Read the relevant rule file in references/ for detailed explanation and examples
- 3.Review the incorrect vs. correct SQL examples to understand the pattern
- 4.Check EXPLAIN output or metrics provided to understand performance impact
- 5.Apply the correct pattern to your code or configuration
Use cases
- Optimizing slow queries by identifying missing or inefficient indexes
- Designing efficient database schemas for new applications
- Implementing Row-Level Security (RLS) policies correctly
- Configuring connection pooling for production deployments
- Reviewing and refactoring existing database code for performance
- Backend developers writing SQL and designing schemas
- Database administrators optimizing Postgres instances
- DevOps engineers configuring database scaling and pooling
- Code review participants evaluating database changes
- Teams using Supabase for their Postgres backend
supabase-postgres-best-practices FAQ
Rules are organized by impact: Query Performance and Connection Management (CRITICAL), Security & RLS (CRITICAL), Schema Design (HIGH), Concurrency & Locking (MEDIUM-HIGH), Data Access Patterns (MEDIUM), Monitoring & Diagnostics (LOW-MEDIUM), and Advanced Features (LOW).
Yes, rule files include Supabase-specific notes where applicable, particularly for features like Row-Level Security and connection pooling.
Yes, each rule file contains incorrect SQL examples with explanations and correct SQL examples with explanations, plus optional EXPLAIN output and performance metrics.
Yes, the rules are designed to guide both automated query optimization and code generation tools.
The guide references PostgreSQL current documentation and best practices applicable across modern Postgres versions.
Full instructions (SKILL.md)
Source of truth, from supabase/agent-skills.
name: supabase-postgres-best-practices description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations. license: MIT metadata: author: supabase version: "1.1.1" organization: Supabase date: January 2026 abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
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
Related skills
More from supabase/agent-skills and the wider catalog.
supabase
Complete Supabase backend integration for databases, auth, storage, and real-time features.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.