skilld
All skills
supabase avatar

/supabase-postgres-best-practices

@3291216 official
by supabasesupabase/agent-skills2.7k stars
214

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.

Ask your Agent

Use this Skill: https://skilld.dev/gh/supabase/agent-skills/supabase-postgres-best-practices

This session only. Nothing lands on disk.

referencesquery-index-types.md

≈381 tokens on demand. Your agent reads this file only when SKILL.md points to it.

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

Source: SKILL.md on GitHub

Third-party checks

No alerts16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides a comprehensive set of Postgres best practices maintained by Supabase, focusing on performance, schema design, and security. It includes specific guidance on Row-Level Security (RLS) and the principle of least privilege to enhance database security. The content is educational and follows established security and performance guidelines for PostgreSQL.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    9/38 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 3291216. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 months ago

Capability

Other metadata
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."
}

Topics

  • Performance
  • postgres
  • supabase
  • query-optimization
  • schema-design
  • indexing
  • connection-pooling
  • rls

README badge

README badge for supabase/agent-skills/supabase-postgres-best-practices

What it does

Guides query optimization, schema design, and connection management for Postgres databases on Supabase through 8 categories of best practices, from query performance and RLS to monitoring and advanced features. Includes SQL examples, EXPLAIN output, and performance metrics for each rule.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with non-Supabase Postgres databases?
Yes. The skill covers general Postgres performance optimization and best practices. While maintained by Supabase and includes Supabase-specific notes where relevant, the core rules apply to any Postgres instance.
What does this skill actually do — does it automatically optimize queries?
No. The skill is a reference guide containing 8 categories of optimization rules with SQL examples, query plan analysis, and performance metrics. It's meant to inform code generation and manual optimization, not to run automated fixes.
Does this cover Row-Level Security (RLS)?
Yes. Security and RLS is one of three critical-priority categories in the skill, with dedicated rules for secure schema and access patterns.
Does this skill include connection pooling guidance?
Yes. Connection management is a critical-priority category with rules on pooling configuration and scaling, marked with the `conn-` prefix.
What if I'm using a different SQL dialect or database?
This skill is Postgres-specific and will not apply to MySQL, SQLite, or other databases. Some concepts may transfer, but query syntax and optimization strategies differ.

Generated from the current SKILL.md. These answers refresh after source changes.