
Supabase Postgres Best Practices
OfficialFreeOptimize your Postgres database with proven guidelines.
Free · Opens the source repo
What Supabase Postgres Best Practices does
The Supabase Postgres Best Practices skill offers a comprehensive guide to optimizing PostgreSQL databases, focusing on performance, schema design, and security. It is particularly useful for developers and database administrators who want to ensure their database interactions are efficient and effective. This skill is structured around eight categories of best practices, prioritized by their impact on database performance and reliability.
When working with PostgreSQL, it is crucial to follow best practices to avoid common pitfalls that can lead to slow queries, inefficient schema designs, or security vulnerabilities. This skill provides detailed instructions and examples for various tasks, including writing SQL queries, implementing indexes, and configuring connection pooling. Each rule is designed to be actionable, with explanations of why certain practices are preferred over others, along with examples of incorrect and correct SQL usage.
The documentation includes specific guidelines for critical areas such as query performance, connection management, and Row-Level Security (RLS). Users can reference individual rule files to dive deeper into specific topics, making it an invaluable resource for anyone involved in managing a PostgreSQL database. The skill is not just a performance guide; it encompasses schema design, security, and SQL authoring tasks, making it relevant for both minor changes and significant database operations.
This skill is particularly beneficial when diagnosing performance issues or planning database migrations. By adhering to these best practices, users can significantly improve the efficiency and security of their PostgreSQL databases, ensuring they are well-optimized for current and future needs.
When to use it
Use this skill when designing schemas, writing SQL queries, or troubleshooting database performance problems.
When not to use it
This skill may not be suitable for users looking for a general database management tool without specific focus on PostgreSQL best practices.
What you can build with it
Optimizing SQL Queries
Reference the best practices when writing SQL queries to ensure they are efficient and performant.
Designing a New Schema
Use the guidelines to design a schema that is both scalable and secure, following recommended practices.
Diagnosing Performance Issues
When encountering slow queries or high CPU usage, consult this skill for troubleshooting techniques and optimization tips.
How to install Supabase Postgres Best Practices
View source1. Install with the skills CLI
npx skills add supabase/agent-skills/supabase-postgres-best-practices --agent claude-code2. Or install it manually
Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.
Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs
Inside SKILL.md
Written by supabaseSupabase 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
Frequently asked questions about Supabase Postgres Best Practices
Similar skills
ClickHouse Logs Queries
Efficiently manage Supabase logs with ClickHouse SQL.
EF Core D2 Database Diagram Generator
Visualize your EF Core models as D2 diagrams effortlessly.
Safe SQL Execution
Ensure secure SQL execution in Supabase applications.
Oracle to PostgreSQL Migration
Identify migration risks between Oracle and PostgreSQL.
SSMA Console
Streamline Oracle to SQL Server migrations with ease.
SQL Performance Optimization
Enhance SQL query efficiency across all databases.
