Postgres field guide / Supabase source01 / Overview

A practical reference for Postgres anywhere

Better database decisions
start with a plan.

Bring Supabase’s prioritized Postgres guidance into your coding assistant: review a schema, reason about a slow query, or check a database change before you apply it.

Observed beforeSeq Scan

100,000 synthetic orders.
The existing query scans the table.

Observed afterIndex Only Scan

The same 20 rows returned.
Zero heap fetches in this local run.

Actual PostgreSQL 18.6 result from one Codex-assisted review. Plan behavior and result equality were checked; no general speed or model-accuracy claim is made.

One rulebook.
Eight places to look.

The Skill loads relevant reference files as needed. Each rule pairs an anti-pattern with a concrete alternative and its rationale.

01
Query performance
Indexes, selectivity and query plans.
Critical
02
Connection management
Pool modes, timeouts and connection budgets.
Critical
03
Security & RLS
Tenant policies and least-privilege roles.
Critical
04
Schema design
Data types, keys, constraints and partitioning.
High
05
Concurrency & locking
Transaction scope, lock order and queue claims.
Medium–high
06
Data access patterns
Batching, keyset pagination and UPSERT.
Medium
07
Monitoring & diagnostics
EXPLAIN, statistics and maintenance.
Low–medium
08
Advanced features
JSONB indexing and full-text search.
Low

Priorities describe the upstream guide’s categories, not measured performance gains. The package contains 31 topic rules and three reference-support files.

Bring the context.

Schema DDL, existing SQL, filters and ordering, row volumes, existing indexes, and an EXPLAIN plan when available. For tenant access, include roles and policies.

Leave with a review.

Postgres-specific recommendations, candidate SQL changes and the reasoning behind them. With authorized database tooling, your assistant can compare plans and verify the result.

Made for

Application engineers, database reviewers and teams checking Postgres schema, indexing, access boundaries or data access code.

Where another tool is needed

This is an instruction library. It does not provision a database, connect to Supabase automatically, operate a migration runner, or monitor a production service.

Readable locally.
Executable with your tools.

Use an Agent Skills compatible assistant that can read local Markdown. No separate API key is needed to read this bundled guidance. Your assistant/model access, subscription and data policies still apply.

Executing SQL requires PostgreSQL and explicit access to a suitable database. Supabase Auth functions, poolers and extensions need their own configured environments.

Keep the examples in context. Upstream impact ranges are illustrative, not guarantees. Its simple missing-FK-index query can accept a partial index that does not cover all rows; inspect the predicate separately. Some guidance is version- and workload-dependent.

Verified here: a genuine local query-plan change with identical rows, FK enforcement, idempotent constraint creation, local RLS isolation, least privilege and sequential UPSERT. Supabase Auth/JWT, pooling, concurrency and production behavior remain untested.