home / skills / fcakyon / claude-codex-settings / supabase-usage

supabase-usage skill

safe

/plugins/supabase-tools/skills/supabase-usage

This skill helps you query supabase, explore schemas, and implement best practices for auth, RLS, relationships, and efficient querying.

npx playbooks add skill fcakyon/claude-codex-settings --skill supabase-usage

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

4.2 KB

---
name: supabase-usage
description: This skill should be used when user asks to "query Supabase", "list Supabase tables", "get Supabase schema", "search Supabase records", "check Supabase database", "Supabase auth", "Supabase authentication", "RLS policy", "row level security", "Supabase foreign key", "table relationships", "Supabase join", "Supabase filter", "Supabase pagination", or needs guidance on Supabase database patterns, auth flows, RLS policies, or query best practices.
---

# Supabase Database Patterns

Patterns for working with Supabase databases including Auth, Row Level Security, table relationships, and query best practices.

## Overview

- **MCP Tools**: Query and explore database structure
- **Authentication**: User management, sessions, auth tables
- **Row Level Security**: Policy patterns for data access control
- **Table Relationships**: Foreign keys, joins, nested queries
- **Query Patterns**: Filtering, pagination, performance

## MCP Tools

Available tools for database exploration:

- `mcp__supabase__list_tables` - List all tables in the database
- `mcp__supabase__get_table_schema` - Get schema for a specific table
- `mcp__supabase__execute_sql` - Run read-only SQL queries

**Workflow:**

1. Start with `list_tables` to understand database structure
2. Use `get_table_schema` to inspect columns and types
3. Use `execute_sql` for custom queries (read-only)

---

## Best Practices

### DO

- ✓ Enable RLS on all public tables
- ✓ Use `(select auth.uid())` in RLS policies for performance
- ✓ Add indexes on RLS-checked columns
- ✓ Specify roles with `TO authenticated` in policies
- ✓ Use `on delete cascade` for foreign keys to auth.users
- ✓ Use cursor-based pagination for large datasets
- ✓ Select only needed columns: `.select('id, name')` not `.select('*')`

### DON'T

- ✗ Store sensitive data without RLS
- ✗ Use `auth.uid()` directly in policies (use `(select auth.uid())`)
- ✗ Create policies without specifying roles
- ✗ Forget indexes on frequently filtered columns
- ✗ Use offset pagination for deep pages (>1000 rows)
- ✗ Expose auth.users directly via API (use public profiles table)

---

## Quick Reference

### Common Filters

| Filter           | JavaScript               | Python                   |
| ---------------- | ------------------------ | ------------------------ |
| Equals           | `.eq('col', val)`        | `.eq("col", val)`        |
| Not equals       | `.neq('col', val)`       | `.neq("col", val)`       |
| Greater than     | `.gt('col', val)`        | `.gt("col", val)`        |
| Greater or equal | `.gte('col', val)`       | `.gte("col", val)`       |
| Less than        | `.lt('col', val)`        | `.lt("col", val)`        |
| Less or equal    | `.lte('col', val)`       | `.lte("col", val)`       |
| Pattern match    | `.ilike('col', '%val%')` | `.ilike("col", "%val%")` |
| In list          | `.in('col', [a,b])`      | `.in_("col", [a,b])`     |
| Is null          | `.is('col', null)`       | `.is_("col", "null")`    |
| OR               | `.or('a.eq.1,b.eq.2')`   | `.or_("a.eq.1,b.eq.2")`  |

### Auth Tables Quick Reference

| Table             | Key Columns                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `auth.users`      | id, email, phone, created_at, last_sign_in_at, raw_user_meta_data |
| `auth.sessions`   | id, user_id, created_at, updated_at                               |
| `auth.identities` | id, user_id, provider, identity_data                              |

### RLS Policy Template

```sql
create policy "policy_name" on table_name
to authenticated  -- or anon, or specific role
for select        -- select, insert, update, delete, or all
using ( (select auth.uid()) = user_id )
with check ( (select auth.uid()) = user_id );  -- for insert/update
```

---

## Additional Resources

For detailed patterns and code examples, consult:

- **`references/auth.md`** - Authentication with JS/Python SDK, user profiles
- **`references/rls.md`** - Row Level Security policies and performance tips
- **`references/relationships.md`** - Table relationships and nested queries
- **`references/query-patterns.md`** - Filtering, pagination, counting, indexes

Overview

This skill helps you inspect and query Supabase databases, design auth flows, and implement secure Row Level Security (RLS) and table relationships. It provides tools and patterns for listing tables, retrieving schemas, running read-only SQL, and applying query best practices for performance and safety. Use it to audit a Supabase schema, build secure policies, or optimize data access patterns.

How this skill works

The skill exposes actions to list all tables, retrieve a table schema, and run read-only SQL queries so you can explore structure and data safely. It guides RLS policy creation using (select auth.uid()) for correct scoping, shows join and foreign-key conventions, and recommends query patterns like cursor-based pagination and selective column projection. It also maps common client filter calls between JavaScript and Python.

When to use it

You need to list or inspect Supabase tables and schemas.
You want to design or audit RLS policies and auth flows.
You need query patterns for filtering, joins, or pagination.
You want to optimize performance with indexes and safe pagination.
You need help mapping client SDK filters between JS and Python.

Best practices

Enable RLS on all public tables and restrict access by role.
Use (select auth.uid()) in policies instead of auth.uid() directly for performance and correctness.
Add indexes on columns used in RLS and frequent filters.
Specify roles in policies (e.g., TO authenticated) and avoid open policies.
Prefer cursor-based pagination for large datasets; avoid deep offset pagination.
Select only required columns (.select('id,name')) to reduce payload and improve performance.

Example use cases

Run list_tables to discover schema and identify public tables to protect.
Inspect a profile or posts table schema before writing RLS policies tied to auth.users.
Create a select/update RLS policy that uses (select auth.uid()) = user_id for per-user rows.
Implement cursor-based pagination with a created_at index for large activity feeds.
Convert a JavaScript filter pattern (.ilike, .in) to the Python client equivalent for a migration script.

FAQ

Should I expose auth.users directly via the API?

No. Avoid exposing auth.users; create a public profiles table and surface only safe profile fields via controlled queries.

When should I use row-level security?

Enable RLS on any table with user-specific or sensitive data. Use role-based policies for system-level access and with-check clauses for inserts/updates to enforce ownership.