SKILL

---
name: postgres-supabase
description: Postgres + Supabase specifics — RLS, migration workflow, schema cache, auth integration, common pitfalls.
category: architecture
version: 0.1.0
triggers: ["supabase", "RLS", "row level security", "auth.uid", "supabase migration"]
applies_to: [openclaw, cursor, claude-code]
---

# Postgres + Supabase

You work with Supabase: Postgres database, auth, storage, edge functions. This skill
captures the platform-specific decisions and traps that the generic database skills don't
cover. Covers self-hosted Postgres too where it overlaps.

## When to use

- Designing or modifying tables on a Supabase project
- Writing or debugging RLS policies
- Setting up auth.users → public schema integration
- Migration workflow (CLI, dashboard, custom scripts)
- Schema cache issues, PostgREST quirks
- Storage bucket policies

Do not invoke for generic schema design (use `architecture/database-schema`) or for
non-Postgres databases.

## Scope

In scope:
- RLS policy design (`SELECT`, `INSERT`, `UPDATE`, `DELETE`, with `USING` and `WITH CHECK`)
- `auth.users` integration: triggers to mirror into `profiles`, FK setup
- Postgres-specific features: `jsonb`, partial indexes, generated columns, materialized views
- PostgREST schema cache and reload (`NOTIFY pgrst, 'reload schema'`)
- Supabase migration workflows (`supabase migration new`, custom apply scripts, dashboard)
- Storage bucket creation and access policies
- Edge functions ↔ DB integration

Out of scope:
- Pure SQL query tuning (use `review/database-review`)
- Frontend Supabase client patterns

## Inherits

- [`architecture/database-schema`](../database-schema/SKILL.md) — base conventions.
- [`architecture/database-migrations`](../database-migrations/SKILL.md) — base migration safety.
- [`meta/engineering-principles`](../../meta/engineering-principles/SKILL.md)
- [`meta/reuse-before-create`](../../meta/reuse-before-create/SKILL.md) — before writing a new RLS policy, helper function, or auth predicate, check existing policies and `auth.*` helpers for one to reuse or extend.
- [`meta/token-discipline`](../../meta/token-discipline/SKILL.md)
## Token discipline (specific)

- Read the project's `supabase/migrations/` directory — last 3–5 files only.
- Read `supabase/config.toml` once if it exists.
- For RLS questions: read the relevant table's existing policies via SQL or migration; do
  not re-read the whole RLS history.
- Skip generated TypeScript types unless types are part of the question.

## RLS — Row Level Security

RLS is **off by default** on a new table. **Turn it on for every table the API touches.**