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.

referencesconn-pooling.md

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

Use Connection Pooling for All Applications

Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.

Incorrect (new connection per request):

-- Each request creates a new connection
-- Application code: db.connect() per request
-- Result: 500 concurrent users = 500 connections = crashed database

-- Check current connections
select count(*) from pg_stat_activity;  -- 487 connections!

Correct (connection pooling):

-- Use a pooler like PgBouncer between app and database
-- Application connects to pooler, pooler reuses a small pool to Postgres

-- Configure pool_size based on: (CPU cores * 2) + spindle_count
-- Example for 4 cores: pool_size = 10

-- Result: 500 concurrent users share 10 actual connections
select count(*) from pg_stat_activity;  -- 10 connections

Pool modes:

  • Transaction mode: connection returned after each transaction (best for most apps)
  • Session mode: connection held for entire session (needed for prepared statements, temp tables)

Reference: Connection Pooling

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.