Preface¶

When using AI programming tools like Cursor or Claude Code to write backend code, generating business logic is usually smooth, but you can easily stumble when working with Postgres: missing indexes on foreign keys, full table scans in queries, exhausted connection pools, RLS only implemented at the application layer… These pitfalls are not noticeable with small local datasets, but will surface after launch in the form of slow queries, timeouts, or even cross-tenant data leaks.

In January 2026, Supabase released supabase-postgres-best-practices, a Postgres best practice Skill for AI Agents. It formalizes the official accumulated rules into the Agent Skills standard format, allowing assistants to cross-reference by priority when modifying tables, writing SQL, configuring RLS, or troubleshooting performance issues, instead of “guessing” based on training memories. After verifying against the official repository and documentation, this article introduces what this Skill is, how to install it, and how to use it.

What is this¶

supabase-postgres-best-practices is a Postgres best practice Skill maintained by Supabase (current metadata version is 1.1.1, MIT licensed). Its positioning is clear: it is not only for Supabase-hosted databases, but also applies to “Postgres running anywhere”.

The official description requires loading this set of rules before creating/modifying tables and columns, working with schemas and migrations, writing RLS and related tests, adding indexes, writing triggers and database functions, handling queues/scheduled tasks (such as pg_cron, pgmq), vector retrieval (pgvector), importing data, and diagnosing problems like slow queries, high CPU usage, timeouts, exhausted connections, lock waits, bloat, and tenant data visibility errors. In other words, it covers performance, as well as schemas, security, and daily SQL writing habits.

Repository address: https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
Skill directory page: https://skills.sh/supabase/agent-skills/supabase-postgres-best-practices
Official introduction blog post: https://supabase.com/blog/postgres-best-practices-for-ai-agents

Core Capabilities: Eight Categories of Rules, Sorted by Impact¶

The Skill itself is SKILL.md, with detailed rules in the references/ directory. Each rule usually includes: why it matters, incorrect examples, correct examples, and optional EXPLAIN/metric explanations; relevant Supabase notes will be included when the rule relates to the platform.

Sorted from highest to lowest impact, the eight categories are as follows (prefixes correspond to rule file names):

The current visible rule files in the repository cover topics such as missing and partial indexes, connection pools and connection limits, RLS basics and performance, primary/foreign keys and data types, deadlocks and short transactions, pagination and batch writes, EXPLAIN ANALYZE and pg_stat_statements, JSONB and full-text search, etc. The official blog post summarized about 30 referenceable rules; the Agent will read the corresponding references/*.md files based on the task, rather than loading all context at once.

Installation and Activation¶

This Skill follows the open Agent Skills format, and can be used in tools that support this standard, such as Cursor, Claude Code, GitHub Copilot, VS Code, and Gemini CLI. The official recommends installing it using Vercel’s skills CLI.

To install only this Skill:

npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

The equivalent syntax is also given on skills.sh (pointing to the same repository):

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

To install the entire supabase/agent-skills repository (including the supabase and this Skill):

npx skills add supabase/agent-skills

By default, it is installed per project scope, and the Skill will be stored in the repository for sharing with colleagues and cloud-based Agents; add the --global flag for a global installation. To update an already installed Skill:

npx skills update

If you are using Claude Code, you can also install it via the plugin marketplace:

claude plugin marketplace add supabase/agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

For more complete installation instructions, see the official documentation: https://supabase.com/docs/guides/getting-started/ai-skills

After installation, no extra activation steps are usually required: when relevant tasks are triggered, the Agent will automatically detect and load the Skill. The official also reminds that MCP (such as Supabase MCP) is responsible for connecting to the database and executing operations, while this Skill is responsible for “how to do it correctly”; when used together, the assistant will have both operational capabilities and rule constraints.

Typical Usage¶

After installation, you can use natural language directly, for example:

Optimize this Postgres query

Review my schema for performance issues

Help me add proper indexes to this table

You can also be more specific about the rule category, such as “write multi-tenant order table policies according to RLS rules and explain the testing method”, or “check if this migration will lock tables for a long time”.

Below is a simplified comparison of official blog post and rule file examples to help you understand how the Agent will reference correct and incorrect writing practices.

1. Missing indexes on WHERE/JOIN columns (query-missing-indexes)

Incorrect: Filtering on unindexed columns on large tables will easily trigger sequential scans.

select * from orders where customer_id = 123;
-- EXPLAIN may show: Seq Scan on orders ...

Correct: Create indexes on frequently used filter columns (and foreign key reference sides):

create index orders_customer_id_idx on orders (customer_id);

select * from orders where customer_id = 123;
-- EXPLAIN may show: Index Scan using orders_customer_id_idx ...

2. Multi-tenant filtering only implemented at the application layer (official blog post RLS example)

Incorrect: Only splicing where user_id = ... in the application code, which will expose the entire table once bypassed.

select * from orders where user_id = $current_user_id;
-- If you write select * from orders;, all orders may be returned

Correct: Enable RLS in the database and use policies to restrict visible rows (using auth.uid() is common in Supabase Auth scenarios):

alter table orders enable row level security;

create policy orders_user_policy on orders
  for all
  to authenticated
  using (user_id = auth.uid());

When writing migrations, modifying schemas, or conducting performance reviews, the Agent will read the detailed rules in references/ by category, then provide suggestions with correct and incorrect comparisons.

Applicable Scenarios and Notes¶

It is suitable for these situations:
- Using AI assistants to write or modify Postgres schemas, migrations, indexes, and queries
- Configuring connection pools and troubleshooting exhausted connections or connection issues under serverless environments
- Designing/reviewing RLS and permissions to avoid “application-layer filtering looks correct but is not enforced at the database layer”
- Conducting performance reviews: slow queries, lock contention, N+1 problems, pagination and batch writes
- Using together with Supabase MCP or CLI to turn “able to execute” into “execute according to rules”

Points to note:
- The Skill provides referenceable rules and examples, and cannot replace real-world EXPLAIN ANALYZE, monitoring, and stress test conclusions.
- Rules are graded by impact level; you still need to make trade-offs based on table size, read/write ratio, and business constraints when implementing (for example, indexes can speed up reads but increase write overhead).
- There is a more product-focused supabase Skill in the repository; prioritize this Skill for pure Postgres optimization, and install the supabase Skill together for product integrations like Auth, Storage, and Edge Functions.
- Supabase will continue to update the rules; it is recommended to regularly run npx skills update for production projects.

Summary¶

supabase-postgres-best-practices organizes the repeated problems Supabase has encountered in hosted Postgres into分级 rules that Agents can load: query and connection management, RLS and schema design, concurrency and locking, data access patterns, then monitoring and advanced features. For people already using AI to write backend code, it fills the gap of “correct Postgres practice” judgment, rather than just another scattered set of document links.

Official address: https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
Installation command: npx skills add supabase/agent-skills --skill supabase-postgres-best-practices