supabase-postgres-best-practices — Claude Code skill for Postgres
The supabase-postgres-best-practices skill guides agents through Postgres schema and SQL work using Supabase-maintained rules. Load it before database changes or when investigating query, connection, and RLS issues.
MIT 146 installs ★ 74 updated 2026-11-02
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a claude-codeWhat supabase-postgres-best-practices does
The skill covers query performance, indexes, connection management, security and RLS, schema design, locking, data access, diagnostics, and advanced Postgres features. Use it for migrations, access policies, bulk loads, or troubleshooting slow queries and timeouts.
Rules are grouped into eight categories. Their files pair incorrect SQL with a corrected example; some also include EXPLAIN output or metrics. For details, the agent can read files under references/, such as references/query-missing-indexes.md. The guide mentions pgvector search alongside the separate postgres-semantic-search skill, so it does not replace that skill. Load this one before changing a schema: its guidance also covers migrations and RLS, not just query speed.
What it helps with
- diagnose a slow SQL query
- choose indexes for a table or query
- review RLS policies for user data access
- investigate timeouts, locks, or connection errors
- improve bulk inserts or UPSERTs
Example prompts for the agent
- Review this migration and suggest suitable column types and indexes.
- Analyze this slow query and tell me what to inspect in its EXPLAIN plan.
- Check whether these RLS policies let users read rows belonging to others.
How to install supabase-postgres-best-practices
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/supabase-postgres-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/supabase-postgres-best-practices/
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a codex2Manually: put the files in place
.agents/skills/supabase-postgres-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a cursor2Manually: put the files in place
.cursor/skills/supabase-postgres-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install laguagu/claude-code-nextjs-skills skills/supabase-postgres-best-practices2Manually: put the files in place
.github/skills/supabase-postgres-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/laguagu/claude-code-nextjs-skills --path skills/supabase-postgres-best-practicesManually: put the files in place
.devin/skills/supabase-postgres-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about supabase-postgres-best-practices
How do I install supabase-postgres-best-practices in Claude Code?
Run npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a claude-code. The skill file is at ~/.claude/skills/supabase-postgres-best-practices/SKILL.md.
What does supabase-postgres-best-practices do?
It gives an agent guidance for Postgres schemas, SQL, indexes, RLS, and diagnosing performance or connection problems. The rules include incorrect and corrected SQL examples.
What areas do the skill's rules cover?
Its eight categories cover query performance, connection management, security and RLS, schema design, locking, data access, diagnostics, and advanced Postgres features.
Source text
SKILL.md · MIT
--- name: supabase-postgres-best-practices description: "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." license: MIT metadata: author: supabase version: "1.1.1" organization: Supabase 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) ## Quick Decision Tree ``` Problem? ├─ Slow query → query-missing-indexes, query-composite-indexes, monitor-explain-analyze ├─ Connection errors / timeouts → conn-pooling, conn-limits, conn-idle-timeout ├─ Deadlocks / long transactions → lock-short-transactions, lock-deadlock-prevention ├─ Bulk load slow → data-batch-inserts, data-upsert ├─ Table bloat / VACUUM issues → monitor-vacuum-analyze ├─ JSONB queries slow → advanced-jsonb-indexing ├─ FTS / search quality → advanced-full-text-search (pair with /postgres-semantic-search for BM25 + vector) └─ Security / multi-tenant → security-* rules, RLS ``` ## Related Skills - `/postgres-semantic-search` — Vector search (pgvector), hybrid BM25 + semantic, ParadeDB - `/ai-sdk` — AI SDK patterns for backend integration ## 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
© supabase · MIT · laguagu/claude-code-nextjs-skills