Skip to content
Supabase Postgres Best Practices

Supabase Postgres Best PracticesSkill

by Supabase
Released
v1.1.1
MIT
Repository Docs
markdown Development

Summary

Supabase's official Postgres skill — eight rule categories ranked by impact, each with wrong-vs-right SQL and EXPLAIN output, for schema, RLS, indexing and query work on Postgres anywhere.

Features

  • Eight rule categories ranked from critical to low impact
  • Each rule pairs incorrect SQL with the corrected version and an EXPLAIN plan
  • Covers RLS policies and the tests that verify tenant isolation
  • Diagnostic rules for slow queries, locking, bloat and connection exhaustion
  • Applies to Postgres anywhere, with Supabase-specific notes called out separately
  • Includes pgvector, pgmq and pg_cron guidance

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

---
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
  date: January 2026
  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)

## 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

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions
npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

npx skills add supabase/agent-skills installs the whole set.

Example Usage

Use the supabase-postgres-best-practices skill to review this migration before I run it — check the index choices, the RLS policy and whether the column types will scale.

Description

Supabase maintains this skill for Postgres generally, not only Postgres on Supabase. Its instruction is to load before touching anything that lives in a database — creating or altering a table, picking a column type, writing a migration or a declarative schema file, adding an RLS policy, an index, a trigger, a database function, a queue or a pg_cron job, setting up pgvector search, or restoring a dump.

It is equally the skill to load when something is already wrong: slow queries, high CPU, timeouts, connection exhaustion, locking, bloat, an EXPLAIN plan you cannot read, or rows visible to the wrong tenant.

How the rules are organised

Eight categories, ordered by impact, each with a rule-file prefix:

  1. Query performance (query-) — critical
  2. Connection management (conn-) — critical
  3. Security and RLS (security-) — critical
  4. Schema design (schema-) — high
  5. Concurrency and locking (lock-) — medium-high
  6. Data access patterns (data-) — medium
  7. Monitoring and diagnostics (monitor-) — low-medium
  8. Advanced features (advanced-) — low

Every rule file follows the same shape: why it matters, an incorrect SQL example with an explanation of the damage, the corrected version, EXPLAIN output or a metric where one is illuminating, and Supabase-specific notes where the managed platform changes the answer.

That structure is what makes it useful to an agent rather than a human reading a blog post — a rule is retrievable by prefix, and the wrong/right pair gives the model a concrete pattern to match against the SQL in front of it.

Version 1.1.1, MIT licensed.

Install

Related Skills

Skill: Supabase

by Supabase

Featured

Supabase's official skill covering Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron and Queues — with a hard rule to verify against the live changelog before writing code.

Development

Skill: EF Core Query Optimization

by .NET Team at Microsoft

Make slow Entity Framework Core queries fast — read the generated SQL first, fix N+1s, cartesian Include explosions and non-sargable predicates, then re-measure one change at a time.

Development

Skill: Google Cloud Spanner Basics

by Google Cloud

Google's official Spanner skill: provision instances, design primary keys that do not hotspot, write SQL and client-library code, and diagnose slow queries — with DDL and DML gated behind your approval.

Development

Skill: ClickHouse Best Practices

by ClickHouse Inc

ClickHouse's official agent skill: 31 rules for primary keys, data types, JOINs, batching and partitioning that an agent must check and cite before advising on a schema or query.

Development
Browse all skills →