⛔ This skill MUST be read in full — not skimmed. Formal review gates depend on its workflow.
Skipping steps silently bypasses quality checks. Missing gates = undetected breakages.

Supabase

Core Principles

1. Supabase changes frequently — verify against current docs before implementing.
Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions. Before implementing, 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. RLS by default in exposed schemas.
Enable RLS on every table in any exposed schema, especially public. This is critical in Supabase because tables in exposed schemas can be reachable through 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.

5. 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.

• RLS, views, and privileged database code

  • Views bypass RLS by default. 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.
  • UPDATE requires a SELECT policy. In Postgres RLS, an UPDATE needs to first SELECT the row. Without a SELECT policy, updates silently return 0 rows — no error, just no change.
  • Do not put security definer functions in an exposed schema. Keep them in a private or otherwise unexposed schema.

• 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.

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

6. Schema safety rules.

When writing queries or touching the database schema, these two habits prevent silent bugs:

• Verify column existence before .select(). Before adding any column to a .select() string, verify the column exists in the database:

  SELECT column_name FROM information_schema.columns 
  WHERE table_name = '<table>' AND column_name = '<column>';

  Never assume a column exists because it appears in a hand-written TypeScript type — types can drift from the real schema after migrations.

• Regenerate types after every migration. After every migration, run and commit the updated types:

  npm run generate:types
  git add src/integrations/supabase/types.ts

  This keeps the generated types in sync so tsc --noEmit catches mapping drift before PRs are created. Commit the types file alongside the .sql migration file.

Also covered by supabase skill (#4696).

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
• When you need a new migration SQL file, always create it with supabase migration new <name> first. Never invent a migration filename or rely on memory for the expected format.

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.

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

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.

For production migrations, use apply_migration_safe from the migration-safe MCP server — never the built-in apply_migration. The built-in writes a runtime timestamp (not the filename timestamp) to schema_migrations, creating a duplicate tracking row when CI later runs supabase db push. Root cause of issue #1830. Full conventions: docs/teams/organisation-design-team/domains (S1)/operations/migration_conventions.md (eldato repo — fetch: gh api repos/daniel-ospina/eldato/contents/<path> --jq .content | base64 -d).

⚠️ Git Stash + Auto-PR Migration Conflict

When apply_migration_safe creates an auto-PR that adds migration files to origin/main, those files arrive on the remote but NOT in your local working tree. If you also had git stash active, popping the stash and pulling will conflict:

error: The following untracked working tree files would be overwritten by merge:
  supabase/migrations/20260710000001_add_business_ratings.sql

Recovery pattern:

⛔ refs/stash is shared by every worktree of the repo, so a bare git stash pop here can take a peer lane's entry and drop their ref (#1264 — see using-git-worktrees). Verify the top entry is this branch's first.

# 1. Abort any in-progress rebase
if git rebase --abort 2>/dev/null; then :; fi

# 2. Remove the conflicting untracked files (they exist on remote, not yet local)
rm -f supabase/migrations/<auto-created-file>.sql

# 3. Now pull, then restore the stash ONLY if the top entry is this worktree's branch
#    (shared register — a peer lane's stash landing on top must not be popped, #1264)
git pull --rebase
TOP="$(git stash list -1 --format='%gs' | sed -n 's/^\(WIP on\|On\) \([^:]*\):.*/\2/p')"
[ "$TOP" = "$(git branch --show-current)" ] \
  && git stash pop \
  || echo "⛔ top stash is '$TOP', not this worktree — do NOT pop (#1264)"

The auto-PR migration file is already merged to main — deleting the local untracked copy just clears the path for the pull to bring it in properly.

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

Reference Guides

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

---

Continue following the workflow as mandated by this skill. Do not skip steps.