Supabase Postgres Best Practices
Give your coding agent Supabase-backed Postgres rules so schemas, queries, RLS, and pooling stay fast and production-safe.
Overview
Supabase Postgres Best Practices is an agent skill most often used in Build (also Ship and Operate) that applies Supabase-maintained Postgres performance rules to writing, reviewing, and optimizing queries, schemas, and
Install
npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practicesWhat is this skill?
- Eight impact-prioritized rule categories from critical query performance through incremental Postgres features
- Incorrect versus correct SQL examples with query-plan context and concrete performance expectations
- Coverage of indexes, connection pooling, scaling, and Row-Level Security for Supabase workloads
Adoption & trust: 217k installs on skills.sh; 2.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are on Supabase or Postgres but agent-generated SQL, indexes, RLS, and pooling choices are slow, opaque, or risky under real traffic.
Who is it for?
Solo builders shipping SaaS or APIs on Supabase who want consistent, high-impact Postgres tuning during schema work, security review, and scaling fixes.
Skip if: Teams on non-Postgres databases, pure NoSQL-only stacks, or builders who only need one-off CRUD without performance or RLS requirements.
When should I use this skill?
Writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations—including indexes, connection pooling, scaling, RLS, and Postgres-specific features.
What do I get? / Deliverables
You get prioritized, example-driven Postgres guidance—indexes, plans, pooling, and RLS patterns—so schema and queries align with Supabase production practice.
- Performance-oriented SQL and schema recommendations aligned to prioritized Postgres rules
- Index, pooling, and RLS guidance tied to incorrect-versus-correct examples
- Review notes on query plans and configuration choices for Supabase workloads
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Database shape and query patterns are decided while building the backend on Supabase or Postgres, so the canonical shelf is Build even though the same rules apply during review and ops. Schema design, SQL, indexes, and Supabase-specific backend configuration belong on the backend subphase rather than generic docs or frontend work.
Where it fits
Shape multi-tenant tables and indexes before your agent generates the first Supabase migration files.
Tune RPC and edge-facing SQL that backs Supabase APIs without N+1 or sequential scan regressions.
Review Row-Level Security policies and query paths so auth rules do not tank planner-friendly access patterns.
Run a pre-release pass on new SQL migrations for missing indexes and anti-patterns called out in the rule set.
Adjust pooling and scaling-related settings when production latency spikes on a lean Supabase project.
How it compares
Procedural best-practices reference for Postgres tuning—not a Supabase CLI replacement, ORM, or automated migration pipeline.
Common Questions / FAQ
Who is supabase-postgres-best-practices for?
It is for solo and indie developers (and small teams) building on Supabase or Postgres who want their agent to follow maintainer-grade performance and configuration rules when touching SQL and schema.
When should I use supabase-postgres-best-practices?
Use it while designing tables and queries in Build, when reviewing RLS and query plans before Ship, and when diagnosing pooling, index, or latency issues in Operate—any time you write, review, or optimize Postgres on Supabase.
Is supabase-postgres-best-practices safe to install?
It is documentation-style guidance under MIT license from Supabase; review the Security Audits panel on this Prism page and your org policy before adding any third-party skill to your agent environment.
SKILL.md
READMESKILL.md - Supabase Postgres Best Practices
# 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 - 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 # Writing Guidelines for Postgres References This document provides guidelines for creating effective Postgres best practice references that work well with AI agents and LLMs. ## Key Principles ### 1. Concrete Transformation Patterns Show exact SQL rewrites. Avoid philosophical advice. **Good:** "Use `WHERE id = ANY(ARRAY[...])` instead of `WHERE id IN (SELECT ...)`" **Bad:** "Design good schemas" ### 2. Error-First Structure Always show the problematic pattern first, then the solution. This trains agents to recognize anti-patterns. ```markdown **Incorrect (sequential queries):** [bad example] **Correct (batched query):** [good example] ``` ### 3. Quantified Impact Include specific metrics. Helps agents prioritize fixes. **Good:** "10x faster queries", "50% smaller index", "Eliminates N+1" **Bad:** "Faster", "Better", "More efficient" ### 4. Self-Contained Examples Examples should be complete and runnable (or close to it). Include `CREATE TABLE` if context is needed. ```sql -- Include table definition when needed for clarity CREATE TABLE users ( id bigint PRIMARY KEY, email text NOT NULL, deleted_at timestamptz ); -- Now show the index CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL; ``` ### 5. Semantic Naming Use meaningful table/column names. Names carry intent for LLMs. **Good:** `users`, `email`, `created_at`, `is_active` **Bad:** `table1`,