Postgres best practices by Supabase
Applies 31 Postgres rules from Supabase, each with wrong and right SQL: indexes, connection pooling, RLS, schema design, locking, pagination and monitoring. Use when writing schemas, migrations, policies or queries, or chasing slow Postgres.
supabase-postgres-best-practices- Author
- Supabase
- Source
- supabase/agent-skills/skills/supabase-postgres-best-practices @ c9be0e9
- License
- MIT · Copyright (c) 2026 Supabase
About this skill
What it does
Supabase's Postgres rule book is a set of 31 short rules for Postgres on any host, Supabase or not. Each sits in its own file in references/ and has the same shape: why it matters, an incorrect SQL example, the corrected one, and sometimes an EXPLAIN plan, a measured gain or a Supabase note. The agent opens only the rules that fit the task.
The file prefix gives the category and its priority. Query performance (query-) and connections (conn-) come first: missing, composite, partial and covering indexes, pooling, connection limits, idle timeouts, prepared statements under transaction pooling. Then security (security-): turning on RLS, keeping policies fast by wrapping auth.uid() in select, least privilege. Schema design (schema-) covers data types, primary keys, indexes on foreign keys, lowercase identifiers, partitioning and adding constraints in migrations, since Postgres has no ADD CONSTRAINT IF NOT EXISTS. After that come locking (short transactions, lock order, SKIP LOCKED, advisory locks), data access (N+1, batch inserts, keyset pagination, upsert), monitoring (EXPLAIN ANALYZE, pg_stat_statements, VACUUM) and two advanced rules on full-text search and JSONB indexes.
references/_sections.md defines the eight categories; _template.md and _contributing.md are for people writing new rules. No scripts, CLI or MCP server are needed.
When to use it, and when not
Use it when writing tables, migrations, RLS policies or indexes, and when a query is slow, connections run out or rows show up for the wrong tenant.
The description asks to load it for almost any Postgres change and also names pgvector, pg_cron, pgmq, pg_restore and RLS tests, but the folder has no rules on those topics. It covers Postgres only, not other engines or ORMs.
How to run it
The install command below puts the whole folder in place.
- Claude Code:
/supabase-postgres-best-practices, or ask for the skill by name. - Codex:
$supabase-postgres-best-practices. - Cursor: type
/in the Agent chat and picksupabase-postgres-best-practices.
Example: /supabase-postgres-best-practices Review db/migrations for missing indexes and RLS policies that will slow down as tables grow.
How it differs from similar skills
Supabase projects from the same pack covers the platform: CLI, MCP, Auth, the Data API and Supabase-specific traps; on Supabase the two work together. SQL query review from our catalog puts wrong results ahead of speed — NULLs, joins that duplicate rows, time zones — across several engines. Safe DB migration plans zero-downtime changes with expand/contract and lock timeouts; this skill has a single migration rule.
Install
Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.
curl -fsSL --create-dirs -o ~/.claude/skills/supabase-postgres-best-practices/SKILL.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/SKILL.md -o ~/.claude/skills/supabase-postgres-best-practices/CHANGELOG.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/CHANGELOG.md -o ~/.claude/skills/supabase-postgres-best-practices/LICENSE https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/LICENSE -o ~/.claude/skills/supabase-postgres-best-practices/references/_contributing.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/_contributing.md -o ~/.claude/skills/supabase-postgres-best-practices/references/_sections.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/_sections.md -o ~/.claude/skills/supabase-postgres-best-practices/references/_template.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/_template.md -o ~/.claude/skills/supabase-postgres-best-practices/references/advanced-full-text-search.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/advanced-full-text-search.md -o ~/.claude/skills/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md -o ~/.claude/skills/supabase-postgres-best-practices/references/conn-idle-timeout.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-idle-timeout.md -o ~/.claude/skills/supabase-postgres-best-practices/references/conn-limits.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-limits.md -o ~/.claude/skills/supabase-postgres-best-practices/references/conn-pooling.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-pooling.md -o ~/.claude/skills/supabase-postgres-best-practices/references/conn-prepared-statements.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-prepared-statements.md -o ~/.claude/skills/supabase-postgres-best-practices/references/data-batch-inserts.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-batch-inserts.md -o ~/.claude/skills/supabase-postgres-best-practices/references/data-n-plus-one.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-n-plus-one.md -o ~/.claude/skills/supabase-postgres-best-practices/references/data-pagination.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-pagination.md -o ~/.claude/skills/supabase-postgres-best-practices/references/data-upsert.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-upsert.md -o ~/.claude/skills/supabase-postgres-best-practices/references/lock-advisory.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-advisory.md -o ~/.claude/skills/supabase-postgres-best-practices/references/lock-deadlock-prevention.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-deadlock-prevention.md -o ~/.claude/skills/supabase-postgres-best-practices/references/lock-short-transactions.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-short-transactions.md -o ~/.claude/skills/supabase-postgres-best-practices/references/lock-skip-locked.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-skip-locked.md -o ~/.claude/skills/supabase-postgres-best-practices/references/monitor-explain-analyze.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/monitor-explain-analyze.md -o ~/.claude/skills/supabase-postgres-best-practices/references/monitor-pg-stat-statements.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/monitor-pg-stat-statements.md -o ~/.claude/skills/supabase-postgres-best-practices/references/monitor-vacuum-analyze.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/monitor-vacuum-analyze.md -o ~/.claude/skills/supabase-postgres-best-practices/references/query-composite-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-composite-indexes.md -o ~/.claude/skills/supabase-postgres-best-practices/references/query-covering-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-covering-indexes.md -o ~/.claude/skills/supabase-postgres-best-practices/references/query-index-types.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-index-types.md -o ~/.claude/skills/supabase-postgres-best-practices/references/query-missing-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-missing-indexes.md -o ~/.claude/skills/supabase-postgres-best-practices/references/query-partial-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-partial-indexes.md -o ~/.claude/skills/supabase-postgres-best-practices/references/schema-constraints.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-constraints.md -o ~/.claude/skills/supabase-postgres-best-practices/references/schema-data-types.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-data-types.md -o ~/.claude/skills/supabase-postgres-best-practices/references/schema-foreign-key-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-foreign-key-indexes.md -o ~/.claude/skills/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md -o ~/.claude/skills/supabase-postgres-best-practices/references/schema-partitioning.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-partitioning.md -o ~/.claude/skills/supabase-postgres-best-practices/references/schema-primary-keys.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-primary-keys.md -o ~/.claude/skills/supabase-postgres-best-practices/references/security-privileges.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/security-privileges.md -o ~/.claude/skills/supabase-postgres-best-practices/references/security-rls-basics.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/security-rls-basics.md -o ~/.claude/skills/supabase-postgres-best-practices/references/security-rls-performance.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/security-rls-performance.md
curl -fsSL --create-dirs -o ~/.agents/skills/supabase-postgres-best-practices/SKILL.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/SKILL.md -o ~/.agents/skills/supabase-postgres-best-practices/CHANGELOG.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/CHANGELOG.md -o ~/.agents/skills/supabase-postgres-best-practices/LICENSE https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/LICENSE -o ~/.agents/skills/supabase-postgres-best-practices/references/_contributing.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/_contributing.md -o ~/.agents/skills/supabase-postgres-best-practices/references/_sections.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/_sections.md -o ~/.agents/skills/supabase-postgres-best-practices/references/_template.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/_template.md -o ~/.agents/skills/supabase-postgres-best-practices/references/advanced-full-text-search.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/advanced-full-text-search.md -o ~/.agents/skills/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md -o ~/.agents/skills/supabase-postgres-best-practices/references/conn-idle-timeout.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-idle-timeout.md -o ~/.agents/skills/supabase-postgres-best-practices/references/conn-limits.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-limits.md -o ~/.agents/skills/supabase-postgres-best-practices/references/conn-pooling.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-pooling.md -o ~/.agents/skills/supabase-postgres-best-practices/references/conn-prepared-statements.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/conn-prepared-statements.md -o ~/.agents/skills/supabase-postgres-best-practices/references/data-batch-inserts.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-batch-inserts.md -o ~/.agents/skills/supabase-postgres-best-practices/references/data-n-plus-one.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-n-plus-one.md -o ~/.agents/skills/supabase-postgres-best-practices/references/data-pagination.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-pagination.md -o ~/.agents/skills/supabase-postgres-best-practices/references/data-upsert.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/data-upsert.md -o ~/.agents/skills/supabase-postgres-best-practices/references/lock-advisory.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-advisory.md -o ~/.agents/skills/supabase-postgres-best-practices/references/lock-deadlock-prevention.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-deadlock-prevention.md -o ~/.agents/skills/supabase-postgres-best-practices/references/lock-short-transactions.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-short-transactions.md -o ~/.agents/skills/supabase-postgres-best-practices/references/lock-skip-locked.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/lock-skip-locked.md -o ~/.agents/skills/supabase-postgres-best-practices/references/monitor-explain-analyze.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/monitor-explain-analyze.md -o ~/.agents/skills/supabase-postgres-best-practices/references/monitor-pg-stat-statements.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/monitor-pg-stat-statements.md -o ~/.agents/skills/supabase-postgres-best-practices/references/monitor-vacuum-analyze.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/monitor-vacuum-analyze.md -o ~/.agents/skills/supabase-postgres-best-practices/references/query-composite-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-composite-indexes.md -o ~/.agents/skills/supabase-postgres-best-practices/references/query-covering-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-covering-indexes.md -o ~/.agents/skills/supabase-postgres-best-practices/references/query-index-types.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-index-types.md -o ~/.agents/skills/supabase-postgres-best-practices/references/query-missing-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-missing-indexes.md -o ~/.agents/skills/supabase-postgres-best-practices/references/query-partial-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/query-partial-indexes.md -o ~/.agents/skills/supabase-postgres-best-practices/references/schema-constraints.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-constraints.md -o ~/.agents/skills/supabase-postgres-best-practices/references/schema-data-types.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-data-types.md -o ~/.agents/skills/supabase-postgres-best-practices/references/schema-foreign-key-indexes.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-foreign-key-indexes.md -o ~/.agents/skills/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-lowercase-identifiers.md -o ~/.agents/skills/supabase-postgres-best-practices/references/schema-partitioning.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-partitioning.md -o ~/.agents/skills/supabase-postgres-best-practices/references/schema-primary-keys.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/schema-primary-keys.md -o ~/.agents/skills/supabase-postgres-best-practices/references/security-privileges.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/security-privileges.md -o ~/.agents/skills/supabase-postgres-best-practices/references/security-rls-basics.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/security-rls-basics.md -o ~/.agents/skills/supabase-postgres-best-practices/references/security-rls-performance.md https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/references/security-rls-performance.md
foreach ($f in 'SKILL.md','CHANGELOG.md','LICENSE','references/_contributing.md','references/_sections.md','references/_template.md','references/advanced-full-text-search.md','references/advanced-jsonb-indexing.md','references/conn-idle-timeout.md','references/conn-limits.md','references/conn-pooling.md','references/conn-prepared-statements.md','references/data-batch-inserts.md','references/data-n-plus-one.md','references/data-pagination.md','references/data-upsert.md','references/lock-advisory.md','references/lock-deadlock-prevention.md','references/lock-short-transactions.md','references/lock-skip-locked.md','references/monitor-explain-analyze.md','references/monitor-pg-stat-statements.md','references/monitor-vacuum-analyze.md','references/query-composite-indexes.md','references/query-covering-indexes.md','references/query-index-types.md','references/query-missing-indexes.md','references/query-partial-indexes.md','references/schema-constraints.md','references/schema-data-types.md','references/schema-foreign-key-indexes.md','references/schema-lowercase-identifiers.md','references/schema-partitioning.md','references/schema-primary-keys.md','references/security-privileges.md','references/security-rls-basics.md','references/security-rls-performance.md') { $p = Join-Path "$HOME\.claude\skills\supabase-postgres-best-practices" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/$f" -UseBasicParsing -OutFile $p }foreach ($f in 'SKILL.md','CHANGELOG.md','LICENSE','references/_contributing.md','references/_sections.md','references/_template.md','references/advanced-full-text-search.md','references/advanced-jsonb-indexing.md','references/conn-idle-timeout.md','references/conn-limits.md','references/conn-pooling.md','references/conn-prepared-statements.md','references/data-batch-inserts.md','references/data-n-plus-one.md','references/data-pagination.md','references/data-upsert.md','references/lock-advisory.md','references/lock-deadlock-prevention.md','references/lock-short-transactions.md','references/lock-skip-locked.md','references/monitor-explain-analyze.md','references/monitor-pg-stat-statements.md','references/monitor-vacuum-analyze.md','references/query-composite-indexes.md','references/query-covering-indexes.md','references/query-index-types.md','references/query-missing-indexes.md','references/query-partial-indexes.md','references/schema-constraints.md','references/schema-data-types.md','references/schema-foreign-key-indexes.md','references/schema-lowercase-identifiers.md','references/schema-partitioning.md','references/schema-primary-keys.md','references/security-privileges.md','references/security-rls-basics.md','references/security-rls-performance.md') { $p = Join-Path "$HOME\.agents\skills\supabase-postgres-best-practices" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/$f" -UseBasicParsing -OutFile $p }Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/supabase/supabase-postgres-best-practices/SKILL.md
SKILL.md
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
Connect through AnyModel API
This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.
AnyModel