home / skills / supabase / agent-skills / supabase-postgres-best-practices

supabase-postgres-best-practices skill

safe

/skills/supabase-postgres-best-practices

This skill helps optimize Postgres queries, schemas, and configs with Supabase best practices to boost performance and security.

npx playbooks add skill supabase/agent-skills --skill supabase-postgres-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (36)

SKILL.md

2.6 KB

---
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.0"
  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/schema-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)

## Full Compiled Document

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

## References

- https://www.postgresql.org/docs/current/
- https://supabase.com/docs
- https://wiki.postgresql.org/wiki/Performance_Optimization
- https://supabase.com/docs/guides/database/overview
- https://supabase.com/docs/guides/auth/row-level-security

Overview

This skill helps developers apply Supabase-backed Postgres performance optimizations and best practices when writing, reviewing, or tuning SQL, schemas, and database configs. It consolidates prioritized rules across query performance, connection management, security (RLS), schema design, and operational monitoring. Use it to surface high-impact fixes and guide automated or manual optimizations.

How this skill works

The skill inspects SQL, schema definitions, and configuration choices against a prioritized rule set maintained by Supabase. It identifies issues like missing indexes, inefficient joins, RLS misconfigurations, and connection pooling problems, then suggests concrete corrections and patterns. Each recommendation links to a focused explanation, example SQL, and Supabase-specific notes for real-world application.

When to use it

Writing or reviewing SQL queries to improve latency and resource use
Designing or refactoring schema and indexes for large tables
Diagnosing production performance problems or slow queries
Configuring connection pooling, scaling, or concurrency behavior
Implementing or auditing Row-Level Security rules

Best practices

Prioritize index and query plan fixes first—these are highest impact
Use connection pooling and tune max connections to avoid overload
Model schemas for common access patterns and prefer partial/indexed columns
Test RLS policies in staging and benchmark their performance
Monitor slow queries, locks, and resource metrics continuously

Example use cases

Detecting missing or unused indexes and proposing targeted CREATE INDEX statements
Rewriting multi-join queries into more efficient forms and showing EXPLAIN comparisons
Suggesting connection pool settings for serverless or high-concurrency workloads
Reviewing schema changes and recommending partial or covering indexes
Auditing RLS policies for correctness and performance impact

FAQ

Will the skill change my schema or data automatically?

No. It provides recommendations, example SQL, and notes. Apply changes manually after review and testing.

Does it cover Supabase-specific features?

Yes. Recommendations include Supabase notes where applicable, such as RLS guidance and platform-specific connection considerations.