supabase-postgres-best-practices
Postgres Best Practices
Postgres Best Practices is Supabase's agent skill of Postgres rules for any Postgres database, ranked by impact: indexes, connection pooling, row level security and schema design.
Install Postgres Best Practices
Install this skill with the skills CLI
npx skills add supabase/agent-skills --skill supabase-postgres-best-practicesOr, for Claude Code, add Supabase's plugin marketplace from your terminal
claude plugin marketplace add supabase/agent-skillsThen install the postgres-best-practices plugin
claude plugin install postgres-best-practices@supabase-agent-skillsOr paste this into your coding agent: Install the agent skill supabase-postgres-best-practices from github.com/supabase/agent-skills.
A skill can include scripts that run on your computer, so read its source first.
What Postgres Best Practices does
Postgres Best Practices is a rule set maintained by Supabase for Postgres running anywhere, not only on Supabase. It loads before an agent writes or changes anything in a Postgres database: tables and column types, migrations, RLS policies and their tests, indexes, triggers, functions, pg_cron and pgmq jobs, pgvector search or data imports. It also loads for slow queries, timeouts, connection exhaustion, locking, bloat, or rows visible to the wrong tenant.
The Postgres Best Practices rules sit in eight categories ranked by impact. Query performance, connection management, and security with row level security are rated critical, and schema design high. Locking, data access patterns, monitoring and advanced features follow. Examples include indexing WHERE, JOIN and foreign key columns, pooling connections, using prepared statements safely with a pooler, cursor pagination instead of OFFSET, and SKIP LOCKED for worker queues.
The Postgres Best Practices security rules cover row level security for multi-tenant data, RLS policies that stay fast, and least privilege for roles. Schema rules cover adding constraints safely in migrations, data types, primary keys and lowercase identifiers. Each rule file explains why it matters and shows incorrect and correct SQL, with EXPLAIN output or metrics where useful and Supabase notes where they apply.
When to use Postgres Best Practices
- You have a query that was fast on test data and is slow in production.
- You are adding row level security to a multi-tenant app and want policies that stay fast.
- You see your app run out of database connections under load or from serverless functions.
- You are writing a migration and want constraints, types and indexes right the first time.
When to pick something else
- Your task is Supabase-specific, such as Auth, Edge Functions or Storage: use the Supabase skill.
Which agents Postgres Best Practices works in
Supabase documents Postgres Best Practices for Claude Code, GitHub Copilot, Cursor, Cline, other agents through the skills CLI (Supabase says 18 or more). The open skills CLI also installs it into 78 agents, including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode (we listed it with the CLI on October 1, 2026). See where each agent looks for skills.
Postgres Best Practices license
Postgres Best Practices is published under MIT.
Questions people ask
Does the Postgres best practices skill only work with Supabase?
No. Supabase maintains it for Postgres running anywhere; Supabase notes appear only in the rules where they apply. It is MIT, per its SKILL.md and the repository's LICENSE file.
Which Postgres problems does the skill rank as critical?
Query performance, connection management, and security with row level security. Schema design is rated high, followed by locking, data access patterns, monitoring and advanced features.
Related skills for databases
- Database migration: database-migration is an agent skill from Seth Hobson's wshobson/agents marketplace for writing schema and data migrations in Sequelize, TypeORM and Prisma, with zero-downtime patterns and rollback strategies.
- Neon Postgres: neon-postgres is Neon's agent skill for working with Postgres on Neon: connection strings, pooled or direct connections, migrations, branching, built-in diagnostics, autoscaling, scale to zero and search.
- Prisma upgrade to v7: prisma-upgrade-v7 is Prisma's agent skill for upgrading a project from Prisma ORM 6 to 7, covering every breaking change: the new generator, driver adapters, prisma.config.ts, ESM and removed features.
- Supabase: Supabase is Supabase's own agent skill for any Supabase task, with a security checklist for auth and row level security and a rule to check the current docs first.