Home › Supabase › Supabase AGENTS.md

Supabase AGENTS.md

AGENTS.md for Supabase projects: local CLI workflow, migrations, Row Level Security, generated types, and Edge Functions.

AGENTS.mdSupabase

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Supabase

## Commands (local first)
- `supabase start` · `supabase migration new <name>` · `supabase db reset` (local only: re-applies migrations and seed) · `supabase gen types typescript --local > src/types/database.ts` · `supabase functions serve`
- Never run `supabase db push`, `db reset --linked`, or anything against the linked remote project without approval.

## Schema
- Every change is a migration in `supabase/migrations/`; don't make schema edits in the dashboard.
- **RLS on every table** in exposed schemas: `alter table ... enable row level security;` plus explicit policies per operation, e.g. `using ((select auth.uid()) = user_id)`. Wrap `auth.uid()` in `select` for performance and index the columns policies use.
- Test policies: a user can't read or write another user's rows (pgTAP tests in `supabase/tests/` or integration tests with two users).
- `security definer` functions only when necessary, with `set search_path = ''`.

## Clients
- Browser/mobile use the anon/publishable key only; the service role/secret key is server-only and bypasses RLS, so use it sparingly.
- Server-side auth with `@supabase/ssr` cookie clients; verify users with `auth.getUser()` (or JWT claims checks) before trusting a session.
- Use generated types: `createClient<Database>(...)`. Regenerate after migrations.

## Edge Functions
- Deno-based in `supabase/functions/<name>/index.ts`; validate input, check the JWT, and read secrets via `Deno.env.get`.

## Done
`supabase db reset` succeeds locally, types are regenerated, and tests pass.