skills / supabase / agent-skills / supabase-postgres-best-practices

Supabase Postgres Best Practices

A performance-first Postgres optimization skill from Supabase covering query tuning, schema design, RLS, and operational best practices.

Source description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or d...

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices
risk: mediuminstall: CLIverified: 2026-02-13

On this page

Our added value (verification layer)

This page is not only a source mirror. We add reproducibility, risk controls, and operations guidance on top of the original skill definition.

  • Execution/Security/Maintainability scoring with explicit criteria
  • Compatibility matrix across runtime environments
  • Verification log with check commands and observed outcomes
  • Common failure fixes and rollback triggers for production safety

Overall score

87/100

Execution

89

Security

85

Maintainability

88

Quick install (universal)

Primary command for most environments:

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices

Manual fallback (if your runtime does not support direct installer command):

  1. npx -y skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices -y -g
  2. Restart your current agent/runtime to reload installed skills.
  3. Run a dry run: "review this slow SQL query and propose index/query fixes".
  • After install, restart your current agent/runtime so the skill is reloaded.
  • Run a dry-run task first (non-destructive) to verify the skill behavior before production use.

SKILL.md (rendered source content)

Readable source reference for this skill. Added verification notes are shown in the sections below.

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

Required permissions

file

Compatibility matrix

EnvironmentStatusNotes
Supabase Postgres projectspassDirectly aligned with Supabase docs and performance practices.
General Postgres deploymentspassMost rules apply broadly beyond Supabase-specific context.
Non-SQL data stacksfailSkill is Postgres-centric and not applicable to non-relational systems.

Verification log

Canonical source exists locally

test -f ~/.agents/skills/supabase-postgres-best-practices/SKILL.md

Pass

result: pass

Install command template validated

npx -y skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices -y -g

Pass

result: pass

Frontmatter + full body extracted

read ~/.agents/skills/supabase-postgres-best-practices/SKILL.md and split description/body

Pass

result: pass

Security notes

  • Treat RLS policies as first-class constraints during optimization.
  • Avoid overbroad indexes that may expose sensitive access patterns.
  • Review migration rollback paths before applying schema changes.

Common failures and fixes

Slow query on large table scans

Add/select proper indexes and validate with EXPLAIN ANALYZE.

Connection exhaustion under burst traffic

Apply connection pooling and reduce long-running transactions.

RLS policies causing unexpected latency

Optimize policy predicates and supporting indexes.

Quick FAQ

How do I install this skill quickly?

Run npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices, then restart your runtime to reload skills.

What should I check before production rollout?

Confirm permissions, run a non-destructive dry run, and review rollback triggers.

What if install succeeds but actions do not run?

Verify SKILL.md location, restart runtime, and check environment/dependency readiness.

Recent changes

  • 2026-02-13: Added hot-skill page entry from Excel priority list.
  • 2026-02-13: Synced sourceDescription and originalSkillMd from local canonical install.
  • 2026-02-13: Added compatibility, fixes, and rollback guidance.

Rollback triggers

  • Latency regresses after index/schema rollout.
  • Connection pool saturation increases after config changes.
  • RLS behavior changes break authorized data access paths.

Known issues

Over-optimization can increase write amplification

Balance read gains vs write costs when adding indexes.

Team adoption gaps on SQL best practices

Adopt query review checklist and shared linting standards.

Related tutorials

Site references