supabase-postgres-best-practices

Files (38)

• AGENTS.md
• CLAUDE.md
• README.md
• SKILL.md
• _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 · references/

SKILL.md (first lines)

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


## Triggers

- supabase
- postgres
- postgresql
- sql
- database query
- rls
- row level security
- realtime
- supabase auth
- pg
- query optimization

## 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/schema-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)

## Verify

- The code was actually executed (or type-checked / linted as appropriate) and the command output is captured
- Dependencies and runtime versions used are pinned and recorded (e.g., requirements.txt, package.json + lockfile, .nvmrc)
- Errors or warnings emitted by the run are addressed or explicitly accepted with a reason
- New external I/O (network, filesystem, DB) has timeouts and error handling, not silent failure
- Tests for the change were run and the pass/fail count is in the transcript
- Secrets and credentials are read from env/secret store, not hard-coded, and `.env` files are not committed

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

From elophanto/EloPhanto, MIT.

More from elophanto/EloPhanto