Skip to content

Commit 789a844

Browse files
gokulkrishhgokulkrishh
committed
Add best practices for Supabase Postgres
- Create documentation for using UPSERT for insert-or-update operations to avoid race conditions. - Document the use of advisory locks for application-level locking to improve coordination. - Provide guidelines on preventing deadlocks with consistent lock ordering. - Emphasize the importance of keeping transactions short to reduce lock contention. - Introduce the SKIP LOCKED feature for non-blocking queue processing. - Recommend using EXPLAIN ANALYZE to diagnose slow queries effectively. - Enable pg_stat_statements for query analysis to identify resource-consuming queries. - Maintain table statistics with VACUUM and ANALYZE for better query performance. - Advocate for creating composite indexes for multi-column queries to enhance efficiency. - Suggest using covering indexes to avoid unnecessary table lookups. - Guide on choosing the right index type based on data characteristics. - Stress the importance of adding indexes on WHERE and JOIN columns to improve query speed. - Recommend using partial indexes for filtered queries to optimize storage and performance. - Provide strategies for safely adding constraints in migrations. - Encourage the selection of appropriate data types to enhance performance and reduce storage. - Highlight the necessity of indexing foreign key columns for faster JOINs and CASCADE operations. - Advise using lowercase identifiers for compatibility across tools and frameworks. - Discuss partitioning large tables for improved performance and maintenance. - Recommend optimal primary key strategies to enhance insert performance and reduce fragmentation. - Apply the principle of least privilege in security practices to minimize risks. - Enable row-level security for multi-tenant data to enforce data access at the database level. - Optimize RLS policies for performance to avoid severe slowdowns in queries.
1 parent 49dfdb1 commit 789a844

39 files changed

Lines changed: 2185 additions & 0 deletions

‎.agents/skills/supabase-postgres-best-practices/AGENTS.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Supabase Postgres Best Practices
2+
3+
## Structure
4+
5+
```
6+
supabase-postgres-best-practices/
7+
SKILL.md # Main skill file - read this first
8+
AGENTS.md # This navigation guide
9+
CLAUDE.md # Symlink to AGENTS.md
10+
references/ # Detailed reference files
11+
```
12+
13+
## Usage
14+
15+
1. Read `SKILL.md` for the main skill instructions
16+
2. Browse `references/` for detailed documentation on specific topics
17+
3. Reference files are loaded on-demand - read only what you need
18+
19+
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.
20+
21+
## When to Apply
22+
23+
Reference these guidelines when:
24+
25+
- Writing SQL queries or designing schemas
26+
- Implementing indexes or query optimization
27+
- Reviewing database performance issues
28+
- Configuring connection pooling or scaling
29+
- Optimizing for Postgres-specific features
30+
- Working with Row-Level Security (RLS)
31+
32+
## Rule Categories by Priority
33+
34+
| Priority | Category | Impact | Prefix |
35+
| -------- | ------------------------ | ----------- | ----------- |
36+
| 1 | Query Performance | CRITICAL | `query-` |
37+
| 2 | Connection Management | CRITICAL | `conn-` |
38+
| 3 | Security & RLS | CRITICAL | `security-` |
39+
| 4 | Schema Design | HIGH | `schema-` |
40+
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
41+
| 6 | Data Access Patterns | MEDIUM | `data-` |
42+
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
43+
| 8 | Advanced Features | LOW | `advanced-` |
44+
45+
## How to Use
46+
47+
Read individual rule files for detailed explanations and SQL examples:
48+
49+
```
50+
references/query-missing-indexes.md
51+
references/schema-partial-indexes.md
52+
references/_sections.md
53+
```
54+
55+
Each rule file contains:
56+
57+
- Brief explanation of why it matters
58+
- Incorrect SQL example with explanation
59+
- Correct SQL example with explanation
60+
- Optional EXPLAIN output or metrics
61+
- Additional context and references
62+
- Supabase-specific notes (when applicable)
63+
64+
## References
65+
66+
- https://www.postgresql.org/docs/current/
67+
- https://supabase.com/docs
68+
- https://wiki.postgresql.org/wiki/Performance_Optimization
69+
- https://supabase.com/docs/guides/database/overview
70+
- https://supabase.com/docs/guides/auth/row-level-security

‎.agents/skills/supabase-postgres-best-practices/CLAUDE.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Supabase Postgres Best Practices
2+
3+
## Structure
4+
5+
```
6+
supabase-postgres-best-practices/
7+
SKILL.md # Main skill file - read this first
8+
AGENTS.md # This navigation guide
9+
CLAUDE.md # Symlink to AGENTS.md
10+
references/ # Detailed reference files
11+
```
12+
13+
## Usage
14+
15+
1. Read `SKILL.md` for the main skill instructions
16+
2. Browse `references/` for detailed documentation on specific topics
17+
3. Reference files are loaded on-demand - read only what you need
18+
19+
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.
20+
21+
## When to Apply
22+
23+
Reference these guidelines when:
24+
25+
- Writing SQL queries or designing schemas
26+
- Implementing indexes or query optimization
27+
- Reviewing database performance issues
28+
- Configuring connection pooling or scaling
29+
- Optimizing for Postgres-specific features
30+
- Working with Row-Level Security (RLS)
31+
32+
## Rule Categories by Priority
33+
34+
| Priority | Category | Impact | Prefix |
35+
| -------- | ------------------------ | ----------- | ----------- |
36+
| 1 | Query Performance | CRITICAL | `query-` |
37+
| 2 | Connection Management | CRITICAL | `conn-` |
38+
| 3 | Security & RLS | CRITICAL | `security-` |
39+
| 4 | Schema Design | HIGH | `schema-` |
40+
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
41+
| 6 | Data Access Patterns | MEDIUM | `data-` |
42+
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
43+
| 8 | Advanced Features | LOW | `advanced-` |
44+
45+
## How to Use
46+
47+
Read individual rule files for detailed explanations and SQL examples:
48+
49+
```
50+
references/query-missing-indexes.md
51+
references/schema-partial-indexes.md
52+
references/_sections.md
53+
```
54+
55+
Each rule file contains:
56+
57+
- Brief explanation of why it matters
58+
- Incorrect SQL example with explanation
59+
- Correct SQL example with explanation
60+
- Optional EXPLAIN output or metrics
61+
- Additional context and references
62+
- Supabase-specific notes (when applicable)
63+
64+
## References
65+
66+
- https://www.postgresql.org/docs/current/
67+
- https://supabase.com/docs
68+
- https://wiki.postgresql.org/wiki/Performance_Optimization
69+
- https://supabase.com/docs/guides/database/overview
70+
- https://supabase.com/docs/guides/auth/row-level-security

‎.agents/skills/supabase-postgres-best-practices/README.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Supabase Postgres Best Practices - Contributor Guide
2+
3+
This skill contains Postgres performance optimization references optimized for
4+
AI agents and LLMs. It follows the [Agent Skills Open Standard](https://agentskills.io/).
5+
6+
## Quick Start
7+
8+
```bash
9+
# From repository root
10+
npm install
11+
12+
# Validate existing references
13+
npm run validate
14+
15+
# Build AGENTS.md
16+
npm run build
17+
```
18+
19+
## Creating a New Reference
20+
21+
1. **Choose a section prefix** based on the category:
22+
- `query-` Query Performance (CRITICAL)
23+
- `conn-` Connection Management (CRITICAL)
24+
- `security-` Security & RLS (CRITICAL)
25+
- `schema-` Schema Design (HIGH)
26+
- `lock-` Concurrency & Locking (MEDIUM-HIGH)
27+
- `data-` Data Access Patterns (MEDIUM)
28+
- `monitor-` Monitoring & Diagnostics (LOW-MEDIUM)
29+
- `advanced-` Advanced Features (LOW)
30+
31+
2. **Copy the template**:
32+
33+
```bash
34+
cp references/_template.md references/query-your-reference-name.md
35+
```
36+
37+
3. **Fill in the content** following the template structure
38+
39+
4. **Validate and build**:
40+
41+
```bash
42+
npm run validate
43+
npm run build
44+
```
45+
46+
5. **Review** the generated `AGENTS.md`
47+
48+
## Skill Structure
49+
50+
```
51+
skills/supabase-postgres-best-practices/
52+
├── SKILL.md # Agent-facing skill manifest (Agent Skills spec)
53+
├── AGENTS.md # [GENERATED] Compiled references document
54+
├── README.md # This file
55+
└── references/
56+
├── _template.md # Reference template
57+
├── _sections.md # Section definitions
58+
├── _contributing.md # Writing guidelines
59+
└── *.md # Individual references
60+
61+
packages/skills-build/
62+
├── src/ # Generic build system source
63+
└── package.json # NPM scripts
64+
```
65+
66+
## Reference File Structure
67+
68+
See `references/_template.md` for the complete template. Key elements:
69+
70+
````markdown
71+
---
72+
title: Clear, Action-Oriented Title
73+
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
74+
impactDescription: Quantified benefit (e.g., "10-100x faster")
75+
tags: relevant, keywords
76+
---
77+
78+
## [Title]
79+
80+
[1-2 sentence explanation]
81+
82+
**Incorrect (description):**
83+
84+
```sql
85+
-- Comment explaining what's wrong
86+
[Bad SQL example]
87+
```
88+
````
89+
90+
**Correct (description):**
91+
92+
```sql
93+
-- Comment explaining why this is better
94+
[Good SQL example]
95+
```
96+
97+
```
98+
## Writing Guidelines
99+
100+
See `references/_contributing.md` for detailed guidelines. Key principles:
101+
102+
1. **Show concrete transformations** - "Change X to Y", not abstract advice
103+
2. **Error-first structure** - Show the problem before the solution
104+
3. **Quantify impact** - Include specific metrics (10x faster, 50% smaller)
105+
4. **Self-contained examples** - Complete, runnable SQL
106+
5. **Semantic naming** - Use meaningful names (users, email), not (table1, col1)
107+
108+
## Impact Levels
109+
110+
| Level | Improvement | Examples |
111+
|-------|-------------|----------|
112+
| CRITICAL | 10-100x | Missing indexes, connection exhaustion |
113+
| HIGH | 5-20x | Wrong index types, poor partitioning |
114+
| MEDIUM-HIGH | 2-5x | N+1 queries, RLS optimization |
115+
| MEDIUM | 1.5-3x | Redundant indexes, stale statistics |
116+
| LOW-MEDIUM | 1.2-2x | VACUUM tuning, config tweaks |
117+
| LOW | Incremental | Advanced patterns, edge cases |
118+
```

‎.agents/skills/supabase-postgres-best-practices/SKILL.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
name: supabase-postgres-best-practices
3+
description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
4+
license: MIT
5+
metadata:
6+
author: supabase
7+
version: "1.1.0"
8+
organization: Supabase
9+
date: January 2026
10+
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.
11+
---
12+
13+
# Supabase Postgres Best Practices
14+
15+
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.
16+
17+
## When to Apply
18+
19+
Reference these guidelines when:
20+
21+
- Writing SQL queries or designing schemas
22+
- Implementing indexes or query optimization
23+
- Reviewing database performance issues
24+
- Configuring connection pooling or scaling
25+
- Optimizing for Postgres-specific features
26+
- Working with Row-Level Security (RLS)
27+
28+
## Rule Categories by Priority
29+
30+
| Priority | Category | Impact | Prefix |
31+
| -------- | ------------------------ | ----------- | ----------- |
32+
| 1 | Query Performance | CRITICAL | `query-` |
33+
| 2 | Connection Management | CRITICAL | `conn-` |
34+
| 3 | Security & RLS | CRITICAL | `security-` |
35+
| 4 | Schema Design | HIGH | `schema-` |
36+
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
37+
| 6 | Data Access Patterns | MEDIUM | `data-` |
38+
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
39+
| 8 | Advanced Features | LOW | `advanced-` |
40+
41+
## How to Use
42+
43+
Read individual rule files for detailed explanations and SQL examples:
44+
45+
```
46+
references/query-missing-indexes.md
47+
references/schema-partial-indexes.md
48+
references/_sections.md
49+
```
50+
51+
Each rule file contains:
52+
53+
- Brief explanation of why it matters
54+
- Incorrect SQL example with explanation
55+
- Correct SQL example with explanation
56+
- Optional EXPLAIN output or metrics
57+
- Additional context and references
58+
- Supabase-specific notes (when applicable)
59+
60+
## References
61+
62+
- https://www.postgresql.org/docs/current/
63+
- https://supabase.com/docs
64+
- https://wiki.postgresql.org/wiki/Performance_Optimization
65+
- https://supabase.com/docs/guides/database/overview
66+
- https://supabase.com/docs/guides/auth/row-level-security

0 commit comments

Comments
 (0)