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-composite-indexes.md

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

Create Composite Indexes for Multi-Column Queries

When queries filter on multiple columns, a composite index is more efficient than separate single-column indexes.

Incorrect (separate indexes require bitmap scan):

-- Two separate indexes
create index orders_status_idx on orders (status);
create index orders_created_idx on orders (created_at);

-- Query must combine both indexes (slower)
select * from orders where status = 'pending' and created_at > '2024-01-01';

Correct (composite index):

-- Single composite index (leftmost column first for equality checks)
create index orders_status_created_idx on orders (status, created_at);

-- Query uses one efficient index scan
select * from orders where status = 'pending' and created_at > '2024-01-01';

Column order matters - place equality columns first, range columns last:

-- Good: status (=) before created_at (>)
create index idx on orders (status, created_at);

-- Works for: WHERE status = 'pending'
-- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
-- Does NOT work for: WHERE created_at > '2024-01-01' (leftmost prefix rule)

Reference: Multicolumn Indexes

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.