postgres-best-practices

SKILL.md

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 Use

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:

rules/query-missing-indexes.md
rules/schema-partial-indexes.md
rules/_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)

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

Use this skill only when the task clearly matches the scope described above.

Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.