New to Claude Skills? Learn how to install them →

supabase on GitHub

Supabase Postgres Best Practices

OfficialFree

Optimize your Postgres database with proven guidelines.

by supabase2.5k stars on supabase/agent-skills
6 views
Updated Jul 30, 2026
Get this skill

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 source

1. Install with the skills CLI

npx skills add supabase/agent-skills/supabase-postgres-best-practices --agent claude-code

2. 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 supabase

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

PriorityCategoryImpactPrefix
1Query PerformanceCRITICALquery-
2Connection ManagementCRITICALconn-
3Security & RLSCRITICALsecurity-
4Schema DesignHIGHschema-
5Concurrency & LockingMEDIUM-HIGHlock-
6Data Access PatternsMEDIUMdata-
7Monitoring & DiagnosticsLOW-MEDIUMmonitor-
8Advanced FeaturesLOWadvanced-

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