skilld
All skills
supabase avatar

/supabase-postgres-best-practices

@3291216 official
by supabasesupabase/agent-skills2.7k stars
214

Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pg_cron, pgmq), vector/semantic search (pgvector), and restoring dumps (pg_restore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.

Ask your Agent

Use this Skill: https://skilld.dev/gh/supabase/agent-skills/supabase-postgres-best-practices

This session only. Nothing lands on disk.

SKILL.md

≈218 tokens always: the name and description. ≈442 when used: this file. ≈15k more on demand in 35 files.

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

Source: SKILL.md on GitHub

Third-party checks

No alerts16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides a comprehensive set of Postgres best practices maintained by Supabase, focusing on performance, schema design, and security. It includes specific guidance on Row-Level Security (RLS) and the principle of least privilege to enhance database security. The content is educational and follows established security and performance guidelines for PostgreSQL.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    9/38 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 3291216. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 months ago

Capability

Other metadata
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."
}

Topics

  • Performance
  • postgres
  • supabase
  • query-optimization
  • schema-design
  • indexing
  • connection-pooling
  • rls

README badge

README badge for supabase/agent-skills/supabase-postgres-best-practices

What it does

Guides query optimization, schema design, and connection management for Postgres databases on Supabase through 8 categories of best practices, from query performance and RLS to monitoring and advanced features. Includes SQL examples, EXPLAIN output, and performance metrics for each rule.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with non-Supabase Postgres databases?
Yes. The skill covers general Postgres performance optimization and best practices. While maintained by Supabase and includes Supabase-specific notes where relevant, the core rules apply to any Postgres instance.
What does this skill actually do — does it automatically optimize queries?
No. The skill is a reference guide containing 8 categories of optimization rules with SQL examples, query plan analysis, and performance metrics. It's meant to inform code generation and manual optimization, not to run automated fixes.
Does this cover Row-Level Security (RLS)?
Yes. Security and RLS is one of three critical-priority categories in the skill, with dedicated rules for secure schema and access patterns.
Does this skill include connection pooling guidance?
Yes. Connection management is a critical-priority category with rules on pooling configuration and scaling, marked with the `conn-` prefix.
What if I'm using a different SQL dialect or database?
This skill is Postgres-specific and will not apply to MySQL, SQLite, or other databases. Some concepts may transfer, but query syntax and optimization strategies differ.

Generated from the current SKILL.md. These answers refresh after source changes.