supabase-postgres-best-practices is a Postgres rule collection maintained by Supabase, including for databases hosted elsewhere. It covers queries, connections, security, schema design, locking, and diagnostics. Bring concrete SQL, table sizes, indexes, roles, and plans rather than only saying the database is slow.
Install and bound the first review
Run this in a terminal inside the project you want to analyze:
npx skills@latest add supabase/agent-skills --skill supabase-postgres-best-practices --agent claude-code
This selects the named skill for Claude Code. Without a global flag, installation is project-scoped. Mention the skill in the conversation and provide your material. Installing rules does not connect to a database or grant database permissions.
Use supabase-postgres-best-practices to review this order query.
I will provide schema.sql, current indexes, and EXPLAIN output.
Explain the evidence before proposing the smallest change, its trade-offs, and a verification method.
Review only; do not execute migrations. Also check whether tenants could see each other's orders.
Explain the plan before adding an index
Describe filters, joins, and typical result sizes. The rules show index candidates for WHERE and JOIN columns, but a sequential scan alone is not a sufficient reason to add one. Consider table size, selectivity, write overhead, and existing indexes. Ask the agent to link each proposal to a query and a measurable expected change rather than create several overlapping indexes.
When plans are available, compare estimated and actual rows, filtered records, loop counts, and buffer reads. EXPLAIN ANALYZE executes the statement. Choose the environment and scope carefully, especially for statements that modify data. Collecting diagnostic evidence should not unexpectedly become a production write operation.
Review access correctness alongside speed
An application-level user_id filter does not itself establish database-enforced tenant isolation. For row-level security, provide roles, policies, and how user identity reaches the database. Supabase authentication context and a custom application's session variables are different designs. Test the current user's rows, another user's rows, and an unauthenticated scenario under the intended roles rather than relying only on an administrator connection.
Compare the same query and role on controlled data before turning a recommendation into a migration. Schema changes also need impact assessment, a rollback approach, and a deployment window appropriate to the project. The skill does not perform that planning automatically. A useful deliverable includes observed evidence, proposed changes, and measurements. Do not copy a sample plan cost or claimed speedup from the guide into conclusions about your own system.
Turn one recommendation into a reviewable change
The entry skill points to rule files grouped by category. When diagnosing a slow query, ask the agent to identify the query-* or monitor-* rule it used and why that rule applies to your SQL. Keep the real query, parameter range, table sizes, existing indexes, and plan together. This avoids the lazy conclusion that every WHERE clause needs a new index. For paginated queries, describe typical offsets or cursor use; for write-heavy tables, include the cost of maintaining another index.
For multi-tenant data, test distinct roles and situations: an authenticated user reading their own rows, reading another user’s rows, an anonymous request, and a backend service role. Express recommendations as executable tests, but first confirm how identity reaches the database and whether RLS is enabled. A successful service-role query does not prove normal users are isolated. A failing role test may indicate incorrect test setup rather than a flawed policy.
A useful final artifact is a small proposed patch plus a validation plan: SQL or policy to change, reasoning, comparison with the same parameters in a test database, and rollback path. Do not casually run EXPLAIN ANALYZE on data-changing statements to gather a plan; it executes them. For connection exhaustion or lock waits, consult the relevant conn-* or lock-* rules instead of blaming every database incident on missing indexes.
Example: a tenant query is slow and may expose another tenant’s data
Suppose an application filters projects by organization_id, but some requests use a backend credential, and developers have observed members occasionally seeing projects outside their organization. Supply a redacted schema, current RLS policies, calling roles, parameters, and the slow-query plan. Ask: “Use supabase-postgres-best-practices to diagnose security and performance separately. Identify what might come from a backend role bypassing RLS versus a normal-user policy error, then inspect filtering and existing indexes. Propose tests and candidate changes only; do not execute on production.”
Verify correctness first: query as ordinary users from two tenants and state exactly which rows each should see. Record service-role behavior separately; it cannot count as a passed user-isolation test. Then compare plans, returned rows, and timing with the same parameters and data scale. If the agent proposes only an index without checking the caller’s role, stop and obtain role evidence. An index can change speed, not repair tenant isolation.
Load these rules for database work
In a long-running project, define when this skill applies: migrations, RLS, indexes, triggers, database functions, and schema or query changes. Ordinary frontend display edits that reuse existing client queries need not load it. A Codex user describes this scoping in their project instructions, keeping database review focused on changes that affect plans, permissions, or schema. Before applying a migration, still inspect the current database and follow the project’s review process.