Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add laguagu/claude-code-nextjs-skills --skill supabase-postgres-best-practices -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/supabase-postgres-best-practices/

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

Similar skills

All skills for Data and databases →
postgres-patterns affaan-m postgres-patterns is a Claude Code skill for PostgreSQL schema design and query tuning, covering indexes, data types, RLS policies, and slow-query diagnosis. CX Codex +1 7,200installs supabase-audit-rpc yoanbernabeu supabase-audit-rpc lists the PostgreSQL functions exposed through Supabase's RPC endpoint and tests each one for RLS bypass and SQL injection. CX Codex +1 576installs supabase-admin curiositech supabase-admin — a skill for Supabase database work: schema design, Row Level Security policies, migrations, and query debugging. It helps when an agent modifies the database structure or figures out why a query returns nothing. CX Codex +1 200installs Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres Ekwo-ai The Ekwo OS — open source accounting: ledger, invoices and VAT on your own Supabase or Postgres MCP server connects Claude Code to accounting for invoices, ledgers, and VAT within user permissions. CX Codex +1 ★ 43repo stars supabase-schema-architect davila7 supabase-schema-architect — a subagent that designs PostgreSQL schemas in Supabase, plans migrations and writes RLS policies. Useful when your database grows and access rules need sorting out. CX Codex 3,839installs supabase-security-audit davila7 Runs a Supabase security audit: RLS policies, permissions, auth setup, and API key handling. Point it at a project and it returns a report with vulnerabilities and fixes. CX Codex +1 1,020installs

From the same set13

The whole set →
nextjs-seo The nextjs-seo Claude Code skill handles SEO implementation and audits for Next.js App Router. It covers metadata, indexing issues, structured data and crawler rules. CX Codex +1 2,600installs openai-agents-sdk This Claude Code skill supports Python development with the OpenAI Agents SDK. It activates for work on agent tools, handoffs, sessions, and streaming. CX Codex +1 2,500installs nextjs-shadcn nextjs-shadcn — a skill for Claude Code that guides Next.js and shadcn/ui development. Activates when building or refining pages, presets, layouts and design system components. CX Codex +1 861installs next-best-practices The next-best-practices Claude Code skill applies Next.js App Router practices while writing or reviewing code. It covers hydration bugs, RSC boundaries, async APIs, and data handling. CX Codex +1 286installs postgres-semantic-search The postgres-semantic-search Claude Code skill builds and tunes PostgreSQL retrieval. It covers semantic and hybrid search, evaluation, and troubleshooting weak results. CX Codex +1 227installs cache-components A skill for mastering Next.js Cache Components and Partial Prerendering in version 16.4+. Advises on the use cache directive, setting cache lifetime with cacheLife(), tagging data with cacheTag(), and invalidating via updateTag(). CX Codex +1 222installs ai-sdk-6 ai-sdk-6 — a skill for projects already on Vercel AI SDK v6. Covers building agents, chatbots, tool integrations, streaming responses and structured output with patterns specific to the v6 API. CX Codex +1 218installs ai-app A skill for Claude Code sets up full-stack Next.js AI applications with AI SDK and shadcn/ui. Activates when generating chatbots, agent dashboards, and custom AI tools. CX Codex +1 198installs

More in the catalog

Project sponsors

Companies that keep this analytics open