Tooluck logoTooluck
SKILL.md

supabase-postgres-best-practices

Agent skill fromsupabase/agent-skills

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.

How to install supabase-postgres-best-practices

install supabase-postgres-best-practices
# install the agent-skills pack with the skills CLI
npx skills add supabase/agent-skills

# or add only this skill to Claude Code: copy the folder

skills/supabase-postgres-best-practices/

# into

~/.claude/skills/supabase-postgres-best-practices/ (all projects)

.claude/skills/supabase-postgres-best-practices/ (one project)

skills/supabase-postgres-best-practices/SKILL.md

MITFull file
1# Supabase Postgres Best Practices
2
3Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
4
5## When to Apply
6
7Reference these guidelines when:
8- Writing SQL queries or designing schemas
9- Implementing indexes or query optimization
10- Reviewing database performance issues
11- Configuring connection pooling or scaling
12- Optimizing for Postgres-specific features
13- Working with Row-Level Security (RLS)
14
15## Rule Categories by Priority
16
17| Priority | Category | Impact | Prefix |
18|----------|----------|--------|--------|
19| 1 | Query Performance | CRITICAL | `query-` |
20| 2 | Connection Management | CRITICAL | `conn-` |
21| 3 | Security & RLS | CRITICAL | `security-` |
22| 4 | Schema Design | HIGH | `schema-` |
23| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
24| 6 | Data Access Patterns | MEDIUM | `data-` |
25| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
26| 8 | Advanced Features | LOW | `advanced-` |
27
28## How to Use
29
30Read individual rule files for detailed explanations and SQL examples:
31
32```
33references/query-missing-indexes.md
34references/query-partial-indexes.md
35references/_sections.md
36```
37
38Each rule file contains:
39- Brief explanation of why it matters
40- Incorrect SQL example with explanation
41- Correct SQL example with explanation
42- Optional EXPLAIN output or metrics
43- Additional context and references
44…

Excerpt shown under the repository's MIT license.

More skills in agent-skills

Keep exploring

Similar skill repositories

Newsletter

Join the Community

Subscribe to our newsletter for the latest news and updates