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.
supabase-server
Use when planning or writing server-side code that uses `@supabase/server` — Edge Functions, Hono apps, webhook handlers, or any backend that creates Supabase clients or validates inbound auth. Trigger **before** writing or modifying any file that imports from `@supabase/server` (or sub-paths like `@supabase/server/core`); calls `withSupabase`, `createSupabaseContext`, `createAdminClient`, `createContextClient`, `verifyAuth`, `verifyCredentials`, or `extractCredentials`; configures an `auth:` mode (`'none'` | `'publishable'` | `'secret'` | `'user'`, or keyed variants like `'secret:*'`); or lives under `supabase/functions/` and authenticates an inbound request. Also trigger during planning — if a plan mentions any of the above, load the skill before drafting code; do not extrapolate `auth:` values or auth modes from neighboring functions. Also trigger when you see legacy patterns to migrate to this package — `Deno.serve`, `createClient(Deno.env.get('SUPABASE_URL'))`, imports from `esm.sh/@supabase` or `deno.land/std`, usage of `SUPABASE_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY`, or the deprecated `allow:` config option / removed `'always'` / `'public'` mode values / removed `authType` field.
vercel-composition-patterns
React composition patterns that scale. Use when refactoring components with
ci-cd-security
Scan GitHub Actions workflows for security vulnerabilities without external tools or execution.
skill-security
Audit AI agent skills for security risks before installing—catches credential theft, prompt injection, malicious code, and intent mismatches.
superdesign
Design agent for frontend UI/UX—create and iterate design drafts before implementation.