Questions? hello@viberation.devGet supportBlogDocsChangelog

Colour mode

XGitHub
Get started

Postgres Best Practices

Skills#backend#database

Supabase's rules for schemas, migrations and queries.

Postgres best practices maintained by Supabase, for Postgres running anywhere. Your agent loads it before creating tables, choosing column types, writing migrations or RLS policies, so the database is right the first time.

Install this skill

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

Runs the open-source skills CLI in your own terminal. It asks which agents to add the skill to. Read what it tells your agent to do before you install it.

Download skill (.zip)

Install for your agent

  • Claude Code

    Run this in your project

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

    Add -g to install it for every project instead.

    Or ask Claude Code to do it

    Install the "supabase-postgres-best-practices" skill from https://github.com/supabase/agent-skills for Claude Code.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .claude/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .claude/skills/ for this project, or ~/.claude/skills/ for all your projects.

    Picked up in the current session, no restart needed.

    Claude Code skills docs
  • Claude.ai

    Upload the ZIP

    1. In Settings > Capabilities, turn on Code execution and file creation.
    2. Go to Customize > Skills, press +, then Create skill.
    3. Choose Upload a skill and pick the ZIP you downloaded.

    Free, Pro and Max plans. On Team and Enterprise, an owner turns skills on in Organization settings first.

    Claude.ai skills docs
  • ChatGPT

    Upload the ZIP

    1. Open Skills in ChatGPT and select Create.
    2. Select Upload from your computer and pick the ZIP you downloaded.
    3. Wait for ChatGPT's safety scan. A skill marked Needs Review asks you to check it before use.

    Skills that rely on scripts or a terminal may not work unchanged in ChatGPT.

    ChatGPT skills docs
  • Codex

    Run this in your project

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

    Add -g to install it for every project instead.

    Or ask Codex to do it

    Install the "supabase-postgres-best-practices" skill from https://github.com/supabase/agent-skills for Codex.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .agents/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .agents/skills/ for this project, or ~/.agents/skills/ for all your projects.

    Restart Codex if the skill does not show up.

    Codex skills docs
  • Cursor

    Run this in your project

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

    Add -g to install it for every project instead.

    Or ask Cursor to do it

    Install the "supabase-postgres-best-practices" skill from https://github.com/supabase/agent-skills for Cursor.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .cursor/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .cursor/skills/ for this project, or ~/.cursor/skills/ for all your projects.

    Run it by typing / and the skill name in chat.

    Cursor skills docs
  • GitHub Copilot

    Run this in your project

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

    Add -g to install it for every project instead.

    Or ask GitHub Copilot to do it

    Install the "supabase-postgres-best-practices" skill from https://github.com/supabase/agent-skills for GitHub Copilot.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .github/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .github/skills/ for this project, or ~/.copilot/skills/ for all your projects.

    Works in Copilot CLI, the cloud agent and agent mode in VS Code and JetBrains.

    GitHub Copilot skills docs
  • Antigravity

    Run this in your project

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

    Add -g to install it for every project instead.

    Or ask Antigravity to do it

    Install the "supabase-postgres-best-practices" skill from https://github.com/supabase/agent-skills for Antigravity.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .agents/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .agents/skills/ for this project, or ~/.gemini/config/skills/ for all your projects.

    Antigravity skills docs
  • Gemini CLI

    Run this in your project

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

    Add -g to install it for every project instead.

    Or ask Gemini CLI to do it

    Install the "supabase-postgres-best-practices" skill from https://github.com/supabase/agent-skills for Gemini CLI.
Copy the skill folder (the one containing SKILL.md, with any scripts or reference files next to it) into .gemini/skills/ in this project.
Before copying, show me the SKILL.md and list any scripts it includes, and wait for me to confirm.

    Or copy the folder yourself

    Unzip the download into .gemini/skills/ for this project, or ~/.gemini/skills/ for all your projects.

    Run /skills to check it was found.

    Gemini CLI skills docs
Installs
399.6K via skills.sh
GitHub
2.6K stars ↗
Last updated
12 Aug 2026
Licence
MIT

Security checks

Run by independent scanners and published on skills.sh. Their results, not a Viberation review.

  • Gen Agent Trust Hub Pass

    This skill provides a comprehensive set of Postgres performance optimization guidelines and best practices. It consists of static markdown documentation and SQL examples, posing no security risks to the environment.

    16 Apr 2026

  • Socket Pass

    No alerts

    16 Apr 2026

  • Snyk Pass

    Risk: LOW · No issues

    16 Apr 2026

  • Runlayer Pass

    9/38 files flagged

    26 Feb 2026

  • ZeroLeaks Pass

    Score: 93/100 · 2 sections analyzed

    16 Apr 2026
What's inside (36 files)
  • CHANGELOG.md5.7K chars
  • references/_contributing.md4.1K chars
  • references/_sections.md1.7K chars
  • references/_template.md1K chars
  • references/advanced-full-text-search.md1.5K chars
  • references/advanced-jsonb-indexing.md1.4K chars
  • references/conn-idle-timeout.md1.3K chars
  • references/conn-limits.md1.3K chars
  • references/conn-pooling.md1.4K chars
  • references/conn-prepared-statements.md1.5K chars
  • references/data-batch-inserts.md1.3K chars
  • references/data-n-plus-one.md1.4K chars
  • references/data-pagination.md1.4K chars
  • references/data-upsert.md1.4K chars
  • references/lock-advisory.md1.5K chars
  • references/lock-deadlock-prevention.md1.9K chars
  • references/lock-short-transactions.md1.4K chars
  • references/lock-skip-locked.md1.4K chars
  • references/monitor-explain-analyze.md1.4K chars
  • references/monitor-pg-stat-statements.md1.4K chars
  • references/monitor-vacuum-analyze.md1.5K chars
  • references/query-composite-indexes.md1.5K chars
  • references/query-covering-indexes.md1.3K chars
  • references/query-index-types.md1.5K chars
  • references/query-missing-indexes.md1.2K chars
  • references/query-partial-indexes.md1.3K chars
  • references/schema-constraints.md1.9K chars
  • references/schema-data-types.md1.5K chars
  • references/schema-foreign-key-indexes.md1.7K chars
  • references/schema-lowercase-identifiers.md1.7K chars
  • references/schema-partitioning.md1.5K chars
  • references/schema-primary-keys.md1.8K chars
  • references/security-privileges.md1.6K chars
  • references/security-rls-basics.md1.4K chars
  • references/security-rls-performance.md2.1K chars
  • SKILL.md3.2K chars

SKILL.md. Shown as plain text.

---
name: supabase-postgres-best-practices
description: "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."
license: MIT
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.
---

# 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

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Query Performance | CRITICAL | `query-` |
| 2 | Connection Management | CRITICAL | `conn-` |
| 3 | Security & RLS | CRITICAL | `security-` |
| 4 | Schema Design | HIGH | `schema-` |
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
| 6 | Data Access Patterns | MEDIUM | `data-` |
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
| 8 | Advanced Features | LOW | `advanced-` |

## How to Use

Read individual rule files for detailed explanations and SQL examples:

```
references/query-missing-indexes.md
references/query-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

- https://www.postgresql.org/docs/current/
- https://supabase.com/docs
- https://wiki.postgresql.org/wiki/Performance_Optimization
- https://supabase.com/docs/guides/database/overview
- https://supabase.com/docs/guides/auth/row-level-security

Key info

Pricing
Open source
Category
Skills

Related reading

  • Fundamentals

    Row level security is the security boundary

    If your database rows are protected by a check in your application code, they are not protected. Anything holding a key can talk to the database directly, an…

    Expert

More in Skills