supabase/SKILL.md

---

name: supabase description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, declarative schemas, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector); debugging and troubleshooting errors or unexpected behavior on Supabase projects (HTTP errors, Postgres errors, RLS surprises, permission denied, schema cache issues, timeouts, Edge Function crashes, Realtime drops, Storage failures) and reading or querying logs (Logs Explorer, ClickHouse)." metadata: author: supabase version: "0.1.2"

---

Supabase

Independent BB Skills adaptation: five PostgreSQL access-control statements are qualified below. The complete pinned original is archived in upstream-original/SKILL.md. Native PostgreSQL observations do not test Supabase Auth, the Data API, CLI, MCP or an AI client. Read SOURCE.md and BB-SKILLS-ADAPTATION.json before use.

Core Principles

1. Supabase changes frequently — verify against changelog and current docs before implementing. Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions.

First, fetch https://supabase.com/changelog.md (a lightweight summary index — not a heavy pull), scan for breaking-change tags relevant to your task, and follow the linked page for any that apply. Then look up the relevant topic using the documentation access methods below.

2. Verify your work. After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete.

3. Recover from errors, don't loop. If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding.

4. Exposing tables to the Data API: Depending on the user's Data API settings, newly created tables may not be automatically exposed via the Data (REST) API. If this is the case, anon and authenticated roles will need to be explicitly granted access.

Note that this is separate from RLS, which controls which rows are visible once a table is accessible, not whether the table is accessible at all.

When a user reports a SQL-created table is unexpectedly inaccessible, check their Data API settings and whether the roles have been granted access via explicit GRANT SQL. When granting public (anon/authenticated) access, always enable RLS too. See Exposing a Table to the Data API for the full setup workflow.

5. RLS in exposed schemas. Enable RLS on every table in any exposed schema, which includes public by default. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API when the anon/authenticated roles have access (see Exposing a Table to the Data API). For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same auth.uid() pattern.

6. Security checklist. When working on any Supabase task that touches auth, RLS, views, storage, or user data, run through this checklist. These are Supabase-specific security traps that silently create vulnerabilities:

• Auth and session security
• Never use user_metadata claims in JWT-based authorization decisions. In Supabase, raw_user_meta_data is user-editable and can appear in auth.jwt(), so it is unsafe for RLS policies or any other authorization logic. Store authorization data in raw_app_meta_data / app_metadata instead.
• Deleting a user does not invalidate existing access tokens. Sign out or revoke sessions first, keep JWT expiry short for sensitive apps, and for strict guarantees validate session_id against auth.sessions on sensitive operations.

• If you use app_metadata or auth.jwt() for authorization, remember JWT claims are not always fresh until the user's token is refreshed.

• API key and client exposure

• Never expose the service_role or secret key in public clients. Prefer publishable keys for frontend code. Legacy anon keys are only for compatibility. In Next.js, any NEXT_PUBLIC_ env var is sent to the browser.

• Use scoped personal access tokens for the Management API, CLI, and MCP server. A classic personal access token carries the user's full account access, on every organization and project. For scripts, CI, and agents, have the user create a scoped token limited to the organizations, projects, and permissions the task needs. The personal access tokens guide lists the permission each Management API endpoint and MCP tool requires. Look permissions up there rather than guessing.

• RLS, views, and privileged database code

• Default views check underlying table privileges and RLS using the view owner, which can expose rows when that owner bypasses the table policies. This is not an unconditional bypass for every view owner. In Postgres 15 and above, use CREATE VIEW ... WITH (security_invoker = true). In older versions of Postgres, protect your views by revoking access from the anon and authenticated roles, or by putting them in an unexposed schema.
• An UPDATE that reads table columns needs the applicable SELECT policy too. Conditions, RETURNING and column-reading SET expressions commonly require SELECT rights. In our conditional UPDATE ... RETURNING fixture, an UPDATE policy alone selected no rows; adding the corresponding SELECT policy allowed the own row. Check the exact statement rather than generalizing this result to every unconditional UPDATE.
• auth.role() is deprecated — use the TO clause instead. Supabase has deprecated auth.role() in favour of specifying the target role directly on the policy with TO authenticated or TO anon. Beyond deprecation, auth.role() = 'authenticated' breaks silently when anonymous sign-ins are enabled, because anonymous users carry the authenticated Postgres role and pass the check regardless of whether the user is genuinely signed in. sql -- Deprecated (do not use) create policy "example" on table_name for select using ( auth.role() = 'authenticated' );
• TO authenticated alone is authentication without authorization (BOLA / IDOR). Using TO authenticated only checks the role — it does not restrict which rows a user can access. The correct pattern combines TO authenticated with an ownership predicate in USING: sql create policy "example" on table_name for select to authenticated using ( (select auth.uid()) = user_id );
• Review existing-row access and proposed-row checks separately. Explicit USING and WITH CHECK clauses make ownership intent clear. PostgreSQL ALL and UPDATE policies reuse USING as WITH CHECK when the latter is omitted, so omission alone does not allow ownership reassignment. Review every applicable policy, including permissive OR combinations; use the explicit example below for clarity: sql create policy "example" on table_name for update to authenticated using ( (select auth.uid()) = user_id ) with check ( (select auth.uid()) = user_id );
• SECURITY DEFINER runs with the function owner's privileges. Whether table RLS applies depends on that effective role: superusers and BYPASSRLS roles bypass it; a table owner normally bypasses it unless FORCE ROW LEVEL SECURITY applies. A non-bypass owner can still be constrained. Changing the function owner can change the outcome. Prefer SECURITY INVOKER where possible; review ownership, grants and a safe search_path before introducing privileged code.

• Review both schema USAGE and function EXECUTE grants. New PostgreSQL functions normally grant EXECUTE to PUBLIC; default privileges and explicit revocation can change that. A caller also needs access to the containing schema, and SQL callability is separate from Data API exposure. For privileged functions, revoke broad EXECUTE and grant only the intended roles within the same creation transaction. Use a non-exposed schema, a safe search_path, an authorization check suited to the actual action, and current Supabase advisors. No keyword or folder alone establishes access control.

• Storage access control

• Storage upsert requires INSERT + SELECT + UPDATE. Granting only INSERT allows new uploads but file replacement (upsert) silently fails. You need all three.

• Dependency and supply-chain security

• Always pin package versions and commit lockfiles when installing Supabase packages (supabase-js, @supabase/ssr, supabase-py, etc.). See the npm security guide for the full checklist.

For any security concern not covered above, fetch the Supabase product security index: https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

Always discover commands via --help — never guess. The CLI structure changes between versions.

supabase --help                    # All top-level commands
supabase <group> --help            # Subcommands (e.g., supabase db --help)
supabase <group> <command> --help  # Flags for a specific command

Supabase CLI Known gotchas:

• supabase db query requires CLI v2.79.0+ → use MCP execute_sql or psql as fallback
• supabase db advisors requires CLI v2.81.3+ → use MCP get_advisors as fallback
• The browser flow of supabase login creates a classic token with full account access. In CI, set SUPABASE_ACCESS_TOKEN to a scoped personal access token instead. It takes precedence over any saved login. Commands that connect with the database password (--password or SUPABASE_DB_PASSWORD, for example supabase db push) aren't limited by the token's permissions.
• In imperative migration projects, create new hand-authored migration files with supabase migration new <name> first. Never invent a migration filename or rely on memory for the expected format. Declarative schema projects generate migrations from supabase/schemas/; see "Making and Committing Schema Changes" below.

Version check and upgrade: Run supabase --version to check. For CLI changelogs and version-specific features, consult the CLI documentation or GitHub releases.

Supabase MCP Server

For setup instructions, server URL, and configuration, see the MCP setup guide.

Troubleshooting connection issues — follow these steps in order:

1. Check if the server is reachable: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp A 401 is expected (no token) and means the server is up. Timeout or "connection refused" means it may be down.

2. Check .mcp.json configuration: Verify the project root has a valid .mcp.json with the correct server URL. If missing, create one pointing to https://mcp.supabase.com/mcp.

3. Authenticate the MCP server: If the server is reachable and .mcp.json is correct but tools aren't visible, the user needs to authenticate. The Supabase MCP server uses OAuth 2.1 — tell the user to trigger the auth flow in their agent, complete it in the browser, and reload the session. In CI or other environments where the browser flow can't run, pass a scoped personal access token in the Authorization: Bearer header instead.

4. Check scoped token permissions: If a tool fails with "You do not have permission to perform this action" while using a scoped personal access token, the token lacks that tool's permission or the project is outside the token's scope. Check the tool's required permission in the personal access tokens guide.

Supabase Documentation

Before implementing any Supabase feature, find the relevant documentation. Use these methods in priority order:

1. MCP search_docs tool (preferred — returns relevant snippets directly)
2. Fetch docs pages as markdown — any docs page can be fetched by appending .md to the URL path.
3. Web search for Supabase-specific topics when you don't know which page to look at.

Making and Committing Schema Changes

First decide which schema workflow the project uses.

Option A: Declarative schemas

Use this when supabase/schemas/ exists or config.toml sets schema_paths. Edit the desired schema state in those files, then generate and review the migration. Do not start by hand-writing a migration. See the Declarative database schemas guide.

Option B: Imperative migrations

Use this when the project does not use declarative schemas.

To make schema changes, use execute_sql (MCP) or supabase db query (CLI). These run SQL directly on the database without creating migration history entries, so you can iterate freely and generate a clean migration when ready.

Do NOT use apply_migration to change a local database schema — it writes a migration history entry on every call, which means you can't iterate, and supabase db diff / supabase db pull will produce empty or conflicting diffs. If you use it, you'll be stuck with whatever SQL you passed on the first try.

When ready to commit your changes to a migration file:

1. Run advisors → supabase db advisors (CLI v2.81.3+) or MCP get_advisors. Fix any issues.
2. Review the Security Checklist above if your changes involve views, functions, triggers, or storage.
3. Generate the migration → supabase db pull <descriptive-name> --local --yes
4. Verify → supabase migration list --local

Debugging

When you get an error on a Supabase-related request, for example an error code from the Supabase REST API, Postgres database, or PostgREST, an empty result, getting blocked by RLS unexpectedly, or an error from a Supabase service like Auth, Realtime, Edge Functions, or Storage, you must fetch Supabase's Monitoring and Debugging documentation before diagnosing or proposing a fix, rather than working from memory. The same docs also cover performance optimizations, such as slow queries and missing indexes.

Reference Guides

• Skill Feedback → references/skill-feedback.md MUST read when the user reports that this skill gave incorrect guidance or is missing information.