AutoGineer
Generated banner for Supabase Postgres Best Practices
Generated logo for Supabase Postgres Best Practices

Supabase Postgres Best Practices

JetBrainsOfficialCreated by SupabaseDistributed by JetBrains

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
— the description by Supabase

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive set of performance-oriented guidelines for PostgreSQL, specifically curated for developers using Supabase. It organizes best practices into eight prioritized categories ranging from critical query performance and connection management to advanced features. Each rule follows a standardized format that includes clear explanations, anti-pattern identification, and concrete SQL transformation examples to help developers and AI agents write more efficient database code.

What it does

  • Provides actionable SQL transformation patterns to replace inefficient queries.
  • Categorizes database best practices by performance impact level.
  • Offers guidance on connection pooling and serverless database configurations.
  • Includes standards for Row-Level Security and schema design.
  • Supplies examples for resolving common issues like N+1 queries and missing indexes.
  • Standardizes the documentation of database performance rules for AI consumption.

When to use it

  • When writing or reviewing SQL queries for production applications.
  • During database schema design to ensure long-term scalability.
  • When troubleshooting slow query performance or high database load.
  • When configuring connection limits or implementing transaction management.
  • When optimizing Row-Level Security policies for better performance.

Advantages

  • Prioritizes optimizations based on real-world performance impact.
  • Uses a consistent error-first structure that makes anti-patterns easy to identify.
  • Provides concrete, runnable SQL examples for immediate application.
  • Includes quantified impact metrics to help developers prioritize tasks.
  • Reduces ambiguity by focusing on specific transformation patterns.

Usage examples

“How can I optimize my Postgres query to avoid N+1 issues when fetching user posts?”
The agent will reference the data-n-plus-one guidelines, showing an incorrect loop-based query followed by a corrected, batched SQL query using the ANY operator.
“What is the best way to handle connection pooling in a serverless environment?”
The agent will provide guidance from the connection management section, explaining the necessity of connection pooling and how to configure it effectively.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/jetbrains/supabase-postgres-best-practices/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip supabase-postgres-best-practices.zip -d .agents/skills

Documentation by Supabase

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

PriorityCategoryImpactPrefix
1Query PerformanceCRITICALquery-
2Connection ManagementCRITICALconn-
3Security & RLSCRITICALsecurity-
4Schema DesignHIGHschema-
5Concurrency & LockingMEDIUM-HIGHlock-
6Data Access PatternsMEDIUMdata-
7Monitoring & DiagnosticsLOW-MEDIUMmonitor-
8Advanced FeaturesLOWadvanced-

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)

References

Files

references/query-index-types.md

title: Choose the Right Index Type for Your Data impact: HIGH impactDescription: 10-100x improvement with correct index type tags: indexes, btree, gin, gist, brin, hash, index-types

Choose the Right Index Type for Your Data

Different index types excel at different query patterns. The default B-tree isn't always optimal.

Incorrect (B-tree for JSONB containment):

-- B-tree cannot optimize containment operators
create index products_attrs_idx on products (attributes);
select * from products where attributes @> '{"color": "red"}';
-- Full table scan - B-tree doesn't support @> operator

Correct (GIN for JSONB):

-- GIN supports @>, ?, ?&, ?| operators
create index products_attrs_idx on products using gin (attributes);
select * from products where attributes @> '{"color": "red"}';

Index type guide:

-- B-tree (default): =, <, >, BETWEEN, IN, IS NULL
create index users_created_idx on users (created_at);

-- GIN: arrays, JSONB, full-text search
create index posts_tags_idx on posts using gin (tags);

-- GiST: geometric data, range types, nearest-neighbor (KNN) queries
create index locations_idx on places using gist (location);

-- BRIN: large time-series tables (10-100x smaller)
create index events_time_idx on events using brin (created_at);

-- Hash: equality-only (slightly faster than B-tree for =)
create index sessions_token_idx on sessions using hash (token);

Reference: Index Types

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Supabase
Publisher
JetBrains (Official)
Distributed by
JetBrains
Source
JetBrains/skills · postgres-best-practices · commit 3f53782
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Supabase or JetBrains.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download supabase-postgres-best-practices.zip