skills/supabase-postgres-best-practices
1
0
Fork 0
mirror of https://github.com/supabase/agent-skills.git synced 2026-03-27 10:09:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

update agents.md

Browse Source
This commit is contained in:
Pedro Rodrigues
2026-02-16 15:07:20 +00:00
parent 51435f97a3
commit fd17b63373
1 changed files with 89 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
skills/supabase/AGENTS.md
View File

@@ -1,10 +1,4 @@
# supabase # Supabase
> **Note:** `CLAUDE.md` is a symlink to this file.
## Overview
Guides and best practices for working with Supabase. Covers getting started, Auth, Database, Storage, Edge Functions, Realtime, supabase-js SDK, CLI, and MCP integration. Use for any Supabase-related questions.
## Structure ## Structure
@@ -22,110 +16,102 @@ supabase/
2. Browse `references/` for detailed documentation on specific topics 2. Browse `references/` for detailed documentation on specific topics
3. Reference files are loaded on-demand - read only what you need 3. Reference files are loaded on-demand - read only what you need
## Reference Categories Supabase is an open source Firebase alternative that provides a Postgres database, authentication, instant APIs, edge functions, realtime subscriptions, and storage. It's fully compatible with Postgres and provides several language sdks, including supabase-js and supabase-py.
| Priority | Category | Impact | Prefix | ## Overview of Resources
|----------|----------|--------|--------|
| 1 | Authentication | CRITICAL | `auth-` |
| 2 | Database | CRITICAL | `db-` |
| 3 | Edge Functions | HIGH | `edge-` |
| 4 | SDK | HIGH | `sdk-` |
| 5 | Realtime | MEDIUM-HIGH | `realtime-` |
| 6 | Storage | HIGH | `storage-` |
Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`). Reference the appropriate resource file based on the user's needs:
## Available References ### Authentication & Security
**Authentication** (`auth-`): | Area | Resource | When to Use |
- `references/auth-core-sessions.md` | ------------------ | ----------------------------------- | -------------------------------------------------------- |
- `references/auth-core-signin.md` | Auth Core | `references/auth-core-*.md` | Sign-up, sign-in, sessions, password reset |
- `references/auth-core-signup.md` | OAuth/Social | `references/auth-oauth-*.md` | Google, GitHub, Apple login, PKCE flow |
- `references/auth-hooks-custom-claims.md` | Enterprise SSO | `references/auth-sso-*.md` | SAML 2.0, enterprise identity providers |
- `references/auth-hooks-send-email-http.md` | MFA | `references/auth-mfa-*.md` | TOTP authenticator apps, phone MFA, AAL levels |
- `references/auth-hooks-send-email-sql.md` | Passwordless | `references/auth-passwordless-*.md`| Magic links, email OTP, phone OTP |
- `references/auth-mfa-phone.md` | Auth Hooks | `references/auth-hooks-*.md` | Custom JWT claims, send email hooks (HTTP and SQL) |
- `references/auth-mfa-totp.md` | Server-Side Auth | `references/auth-server-*.md` | Admin API, SSR with Next.js/SvelteKit, service role auth |
- `references/auth-oauth-pkce.md`
- `references/auth-oauth-providers.md`
- `references/auth-passwordless-magic-links.md`
- `references/auth-passwordless-otp.md`
- `references/auth-server-admin-api.md`
- `references/auth-server-ssr.md`
- `references/auth-sso-saml.md`
**Database** (`db-`): ### Database
- `references/db-conn-pooling.md`
- `references/db-migrations-diff.md`
- `references/db-migrations-idempotent.md`
- `references/db-migrations-testing.md`
- `references/db-perf-indexes.md`
- `references/db-perf-query-optimization.md`
- `references/db-rls-common-mistakes.md`
- `references/db-rls-mandatory.md`
- `references/db-rls-performance.md`
- `references/db-rls-policy-types.md`
- `references/db-rls-views.md`
- `references/db-schema-auth-fk.md`
- `references/db-schema-extensions.md`
- `references/db-schema-jsonb.md`
- `references/db-schema-realtime.md`
- `references/db-schema-timestamps.md`
- `references/db-security-functions.md`
- `references/db-security-service-role.md`
**Edge Functions** (`edge-`): | Area | Resource | When to Use |
- `references/edge-adv-regional.md` | ------------------ | ------------------------------- | ---------------------------------------------- |
- `references/edge-adv-streaming.md` | RLS Security | `references/db-rls-*.md` | Row Level Security policies, common mistakes |
- `references/edge-adv-websockets.md` | Connection Pooling | `references/db-conn-pooling.md` | Transaction vs Session mode, port 6543 vs 5432 |
- `references/edge-auth-jwt-verification.md` | Schema Design | `references/db-schema-*.md` | auth.users FKs, timestamps, JSONB, extensions |
- `references/edge-auth-rls-integration.md` | Migrations | `references/db-migrations-*.md` | CLI workflows, idempotent patterns, db diff |
- `references/edge-db-direct-postgres.md` | Performance | `references/db-perf-*.md` | Indexes (BRIN, GIN), query optimization |
- `references/edge-db-supabase-client.md` | Security | `references/db-security-*.md` | Service role key, security_definer functions |
- `references/edge-dbg-limits.md`
- `references/edge-dbg-testing.md`
- `references/edge-fun-project-structure.md`
- `references/edge-fun-quickstart.md`
- `references/edge-pat-background-tasks.md`
- `references/edge-pat-cors.md`
- `references/edge-pat-error-handling.md`
- `references/edge-pat-routing.md`
**Realtime** (`realtime-`): ### Edge Functions
- `references/realtime-broadcast-basics.md`
- `references/realtime-broadcast-database.md`
- `references/realtime-patterns-cleanup.md`
- `references/realtime-patterns-debugging.md`
- `references/realtime-patterns-errors.md`
- `references/realtime-postgres-changes.md`
- `references/realtime-presence-tracking.md`
- `references/realtime-setup-auth.md`
- `references/realtime-setup-channels.md`
**SDK** (`sdk-`): | Area | Resource | When to Use |
- `references/sdk-client-browser.md` | ---------------------- | ------------------------------------- | -------------------------------------- |
- `references/sdk-client-config.md` | Quick Start | `references/edge-fun-quickstart.md` | Creating and deploying first function |
- `references/sdk-client-server.md` | Project Structure | `references/edge-fun-project-structure.md` | Directory layout, shared code, fat functions |
- `references/sdk-error-handling.md` | JWT Authentication | `references/edge-auth-jwt-verification.md` | JWT verification, jose library, middleware |
- `references/sdk-framework-nextjs.md` | RLS Integration | `references/edge-auth-rls-integration.md` | Passing auth context, user-scoped queries |
- `references/sdk-perf-queries.md` | Database (supabase-js) | `references/edge-db-supabase-client.md` | Queries, inserts, RPC calls |
- `references/sdk-perf-realtime.md` | Database (Direct) | `references/edge-db-direct-postgres.md` | Postgres pools, Drizzle ORM |
- `references/sdk-query-crud.md` | CORS | `references/edge-pat-cors.md` | Browser requests, preflight handling |
- `references/sdk-query-filters.md` | Routing | `references/edge-pat-routing.md` | Multi-route functions, Hono framework |
- `references/sdk-query-joins.md` | Error Handling | `references/edge-pat-error-handling.md` | Error responses, validation |
- `references/sdk-query-rpc.md` | Background Tasks | `references/edge-pat-background-tasks.md` | waitUntil, async processing |
- `references/sdk-ts-generation.md` | Streaming | `references/edge-adv-streaming.md` | SSE, streaming responses |
- `references/sdk-ts-usage.md` | WebSockets | `references/edge-adv-websockets.md` | Bidirectional communication |
| Regional Invocation | `references/edge-adv-regional.md` | Region selection, latency optimization |
| Testing | `references/edge-dbg-testing.md` | Deno tests, local testing |
| Limits & Debugging | `references/edge-dbg-limits.md` | Troubleshooting, runtime limits |
**Storage** (`storage-`): ### Realtime
- `references/storage-access-control.md`
- `references/storage-cdn-caching.md`
- `references/storage-download-urls.md`
- `references/storage-ops-file-management.md`
- `references/storage-transform-images.md`
- `references/storage-upload-resumable.md`
- `references/storage-upload-standard.md`
--- | Area | Resource | When to Use |
| ---------------- | ------------------------------------ | ----------------------------------------------- |
| Channel Setup | `references/realtime-setup-*.md` | Creating channels, naming conventions, auth |
| Broadcast | `references/realtime-broadcast-*.md` | Client messaging, database-triggered broadcasts |
| Presence | `references/realtime-presence-*.md` | User online status, shared state tracking |
| Postgres Changes | `references/realtime-postgres-*.md` | Database change listeners (prefer Broadcast) |
| Patterns | `references/realtime-patterns-*.md` | Cleanup, error handling, React integration |
*77 reference files across 6 categories* ### SDK (supabase-js)
| Area | Resource | When to Use |
| --------------- | ------------------------------- | ----------------------------------------- |
| Client Setup | `references/sdk-client-*.md` | Browser/server client, SSR, configuration |
| TypeScript | `references/sdk-ts-*.md` | Type generation, using Database types |
| Query Patterns | `references/sdk-query-*.md` | CRUD, filters, joins, RPC calls |
| Error Handling | `references/sdk-error-*.md` | Error types, retries, handling patterns |
| SDK Performance | `references/sdk-perf-*.md` | Query optimization, realtime cleanup |
| Framework | `references/sdk-framework-*.md` | Next.js App Router, middleware setup |
### Storage
| Area | Resource | When to Use |
| --------------- | ------------------------------------- | ---------------------------------------------- |
| Access Control | `references/storage-access-control.md`| Bucket policies, RLS for storage |
| Standard Upload | `references/storage-upload-standard.md`| File uploads up to 5GB |
| Resumable Upload| `references/storage-upload-resumable.md`| Large file uploads with TUS protocol |
| Downloads | `references/storage-download-urls.md` | Public URLs, signed URLs, download methods |
| Transformations | `references/storage-transform-images.md`| Image resize, crop, format conversion |
| CDN & Caching | `references/storage-cdn-caching.md` | Cache control, Smart CDN, stale content |
| File Operations | `references/storage-ops-file-management.md`| Move, copy, delete, list files |
**CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members.
## Supabase Documentation
Everytime something is not clear, or you want to double-check something, reference the official Supabase documentation. It is the source of truth for all things Supabase and is regularly updated with the latest information, best practices, and examples. - [Supabase Documentation](https://supabase.com/docs). The documentation is available in html format on the website, but you can also fetch plain text versions of specific sections using the following endpoints:
**Documentation:**
```bash
# Index of all available docs
curl https://supabase.com/llms.txt
# Fetch all guides as plain text
curl https://supabase.com/llms/guides.txt
# Fetch JavaScript SDK reference
curl https://supabase.com/llms/js.txt