Back to skills

Agent Skill

Supabase Postgres Best Practices

supabase-postgres-best-practices

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.

SupabaseBackendTypeScriptAiAi-agentsSkillsSupabase
github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices

345K installs

•

supabase/agent-skills

•

by Supabase

Score

8.5

/ 10

Installs

345K

Repo Stars

2.5K

Last Updated

0d ago

Fresh

Quality Ratio

100%

Description

Verified

Language

TypeScript

First Published

Jan 2026

Summary

The Supabase Postgres Best Practices agent skill provides a comprehensive, prioritized guide for optimizing Postgres database performance, security, and schema design. This agent skill is designed for developers, database administrators, and architects seeking to build and maintain high-performance, secure Postgres databases, especially within Supabase environments. It is a well-adopted skill with solid traction in the registry. It contains expert-curated rules across eight categories, prioritizing critical areas like query performance, connection management, and Row-Level Security. This enables the AI agent to analyze database operations, offering practical advice and examples of correct and incorrect SQL to identify and resolve common performance and security anti-patterns during query writing or schema reviews.

Skill Definition

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

PriorityCategoryImpactPrefix
1Query PerformanceCRITICALquery-
2Connection ManagementCRITICALconn-
3Security & RLSCRITICALsecurity-
4Schema DesignHIGHschema-
5Concurrency & LockingMEDIUM-HIGHlock-
6Data Access PatternsMEDIUMdata-
7Monitoring & DiagnosticsLOW-MEDIUMmonitor-
8Advanced FeaturesLOWadvanced-

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

How to Use

Use in O-mega

Claude Code

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