--- title: "supabase/agent-skills" description: "Agent Skills to help developers using AI agents with Supabase" source: https://github.com/supabase/agent-skills ref: main license: MIT licenseName: "MIT License" canonical: https://skillsdocs.com/supabase/agent-skills base: https://github.com/supabase/agent-skills/blob/main/ provenance: authored chapters: 2 inlined: 2 withheld: 0 words: 1744 updated: 2026-09-24T09:55:45Z generator: "Skills Docs" --- > **supabase/agent-skills** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/supabase/agent-skills > Per-skill Markdown: https://skillsdocs.com/supabase/agent-skills/.md > Machine manifest: https://skillsdocs.com/supabase/agent-skills/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/supabase/agent-skills > Install: `npx skills add supabase/agent-skills` > Upstream: https://github.com/supabase/agent-skills @ `main` > Licence: MIT > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/DreambaseAI/skillsdocs/issues/new?labels=takedown&title=Takedown+request # supabase/agent-skills Agent Skills to help developers using AI agents with Supabase - **Skills:** 2 - **Inlined:** 2 (licence detected) - **Words:** 1,744 - **Reading time:** 8 min - **Stars:** 2,649 ## Table of contents 1. [supabase-postgres-best-practices](https://skillsdocs.com/supabase/agent-skills/supabase-postgres-best-practices.md) — Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres dat… 2. [supabase](https://skillsdocs.com/supabase/agent-skills/supabase.md) — Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libr… ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/supabase/agent-skills/blob/main/._ ![Supabase Agent Skills](https://github.com/supabase/agent-skills/blob/main/assets/og.png) # Supabase Agent Skills Agent Skills to help developers using AI agents with Supabase. Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Compatible with 18+ AI agents including Claude Code, GitHub Copilot, Cursor, Cline, and many others. The skills in this repo follow the [Agent Skills](https://agentskills.io/) format. ## Installation See the [Supabase AI Skills documentation](https://supabase.com/docs/guides/getting-started/ai-skills) for detailed installation instructions. ### Install all skills ```bash npx skills add supabase/agent-skills ``` ### Install a specific skill ```bash npx skills add supabase/agent-skills --skill supabase npx skills add supabase/agent-skills --skill supabase-postgres-best-practices ``` ### Claude Code Plugin You can also install the skills as Claude Code plugins: ```bash # 1. Install supabase/agent-skill marketplace claude plugin marketplace add supabase/agent-skills # 2. Install the plugin that you want claude plugin install supabase@supabase-agent-skills claude plugin install postgres-best-practices@supabase-agent-skills ``` ## Available Skills
supabase Comprehensive Supabase development skill covering all Supabase products and integrations. **Use when:** - Working with any Supabase product (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues) - Using client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix - Troubleshooting auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS) - Using the Supabase CLI or MCP server - Working with schema changes, migrations, security audits, or Postgres extensions (pg_graphql, pg_cron, pg_vector)
supabase-postgres-best-practices Postgres performance optimization guidelines from Supabase. Contains references across 8 categories, prioritized by impact. **Use when:** - Writing SQL queries or designing schemas - Implementing indexes or query optimization - Reviewing database performance issues - Configuring connection pooling or scaling - Working with Row-Level Security (RLS) **Categories covered:** - Query Performance (Critical) - Connection Management (Critical) - Schema Design (High) - Concurrency & Locking (Medium-High) - Security & RLS (Critical) - Data Access Patterns (Medium) - Monitoring & Diagnostics (Low-Medium) - Advanced Features (Low)
## Usage Skills are automatically available once installed. The agent will use them when relevant tasks are detected. **Examples:** ``` Optimize this Postgres query ``` ``` Review my schema for performance issues ``` ``` Help me set up Supabase Auth with Next.js ``` ``` Help me add proper indexes to this table ``` ## Skill Structure Each skill follows the [Agent Skills Open Standard](https://agentskills.io/): - `SKILL.md` - Required skill manifest with frontmatter (name, description, metadata) - `references/` - (Optional) Reference files for detailed documentation ## `.well-known` discovery Each release uploads a `dist/index.json` alongside the skill tarballs. This index conforms to the [agent-skills `.well-known` URI spec](https://github.com/agentskills/agentskills/pull/254) (schema v0.2.0) and is consumed by `supabase.com` to serve skills at `https://supabase.com/.well-known/agent-skills/`. The release artifacts are built by `scripts/build-release.ts` and triggered by [Release Please](https://github.com/googleapis/release-please) on every semver release. ### Migrating to the official GitHub Action [`jonathanhefner/agentskills-build-for-well-known`](https://github.com/jonathanhefner/agentskills-build-for-well-known) is intended to be transferred to the `agentskills` org and published to the GitHub Marketplace. When that happens, `scripts/build-release.ts` and the `pnpm build:release` step in `release-please.yml` can be replaced with the Action directly: ```yaml - name: Build release artifacts uses: agentskills/build-for-well-known@v1 # replaces pnpm build:release with: skills-dir: skills output-dir: dist ``` Everything else — the Release Please trigger, the upload step, the supabase-plugin dispatch — stays exactly the same. The script and the Action produce identical output, so it is a drop-in swap. --- ## 1. supabase-postgres-best-practices - **Source:** https://github.com/supabase/agent-skills/blob/main/skills/supabase-postgres-best-practices/SKILL.md - **Raw:** https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/SKILL.md - **Markdown:** https://skillsdocs.com/supabase/agent-skills/supabase-postgres-best-practices.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (35), referenced from this skill's directory: - `CHANGELOG.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/CHANGELOG.md - `references/_contributing.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/_contributing.md - `references/_sections.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/_sections.md - `references/_template.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/_template.md - `references/advanced-full-text-search.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/advanced-full-text-search.md - `references/advanced-jsonb-indexing.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md - `references/conn-idle-timeout.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/conn-idle-timeout.md - `references/conn-limits.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/conn-limits.md - `references/conn-pooling.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/conn-pooling.md - `references/conn-prepared-statements.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/conn-prepared-statements.md - `references/data-batch-inserts.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/data-batch-inserts.md - `references/data-n-plus-one.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/data-n-plus-one.md - `references/data-pagination.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/data-pagination.md - `references/data-upsert.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/data-upsert.md - `references/lock-advisory.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/lock-advisory.md - `references/lock-deadlock-prevention.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/lock-deadlock-prevention.md - `references/lock-short-transactions.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/lock-short-transactions.md - `references/lock-skip-locked.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/lock-skip-locked.md - `references/monitor-explain-analyze.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/monitor-explain-analyze.md - `references/monitor-pg-stat-statements.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/monitor-pg-stat-statements.md - `references/monitor-vacuum-analyze.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/monitor-vacuum-analyze.md - `references/query-composite-indexes.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/query-composite-indexes.md - `references/query-covering-indexes.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/query-covering-indexes.md - `references/query-index-types.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase-postgres-best-practices/references/query-index-types.md - …and 11 more, listed in https://skillsdocs.com/api/v1/books/supabase/agent-skills/skills/supabase-postgres-best-practices --- name: supabase-postgres-best-practices description: "Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pg_cron, pgmq), vector/semantic search (pgvector), and restoring dumps (pg_restore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query." license: MIT metadata: author: supabase version: "1.1.1" organization: Supabase date: January 2026 abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation. --- # Supabase Postgres Best Practices Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design. ## When to Apply Reference these guidelines when: - Writing SQL queries or designing schemas - Implementing indexes or query optimization - Reviewing database performance issues - Configuring connection pooling or scaling - Optimizing for Postgres-specific features - Working with Row-Level Security (RLS) ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Query Performance | CRITICAL | `query-` | | 2 | Connection Management | CRITICAL | `conn-` | | 3 | Security & RLS | CRITICAL | `security-` | | 4 | Schema Design | HIGH | `schema-` | | 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` | | 6 | Data Access Patterns | MEDIUM | `data-` | | 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` | | 8 | Advanced Features | LOW | `advanced-` | ## How to Use Read individual rule files for detailed explanations and SQL examples: ``` references/query-missing-indexes.md references/query-partial-indexes.md references/_sections.md ``` Each rule file contains: - Brief explanation of why it matters - Incorrect SQL example with explanation - Correct SQL example with explanation - Optional EXPLAIN output or metrics - Additional context and references - Supabase-specific notes (when applicable) ## References - https://www.postgresql.org/docs/current/ - https://supabase.com/docs - https://wiki.postgresql.org/wiki/Performance_Optimization - https://supabase.com/docs/guides/database/overview - https://supabase.com/docs/guides/auth/row-level-security --- ## 2. supabase - **Source:** https://github.com/supabase/agent-skills/blob/main/skills/supabase/SKILL.md - **Raw:** https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase/SKILL.md - **Markdown:** https://skillsdocs.com/supabase/agent-skills/supabase.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (3), referenced from this skill's directory: - `assets/feedback-issue-template.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase/assets/feedback-issue-template.md - `CHANGELOG.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase/CHANGELOG.md - `references/skill-feedback.md` — https://raw.githubusercontent.com/supabase/agent-skills/main/skills/supabase/references/skill-feedback.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 ## 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](https://supabase.com/dashboard/project//integrations/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](https://supabase.com/docs/guides/api/securing-your-api.md) 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](https://supabase.com/docs/guides/api/securing-your-api.md)). 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](https://supabase.com/docs/guides/platform/personal-access-tokens.md) lists the permission each Management API endpoint and MCP tool requires. Look permissions up there rather than guessing. - **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. - **`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 ); ``` - **UPDATE policies require both `USING` and `WITH CHECK`.** Without `WITH CHECK`, a user can reassign a row's `user_id` to another user: ```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` functions bypass RLS.** A `SECURITY DEFINER` function runs with its creator's privileges — typically a role with `bypassrls` (e.g., `postgres`). Never add `SECURITY DEFINER` to resolve a permission error; it silently removes access control without fixing the underlying cause. Prefer `SECURITY INVOKER`. - **`SECURITY DEFINER` functions in `public` are callable by all roles.** Postgres grants `EXECUTE` to `PUBLIC` by default for every new function, so any `SECURITY DEFINER` function in `public` is a public API endpoint callable by `anon` and `authenticated` (which inherit from `PUBLIC`) without any additional grant. When `SECURITY DEFINER` is genuinely needed (e.g., bypassing RLS on an internal lookup table), keep the function in a non-exposed schema, always include an `auth.uid()` check in the function body, and run `supabase db advisors` after making changes. - **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](https://supabase.com/docs/guides/security/npm-security.md) 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. ```bash supabase --help # All top-level commands supabase --help # Subcommands (e.g., supabase db --help) supabase --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 ` 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](https://supabase.com/docs/reference/cli/introduction) or [GitHub releases](https://github.com/supabase/cli/releases). ## Supabase MCP Server For setup instructions, server URL, and configuration, see the [MCP setup guide](https://supabase.com/docs/guides/getting-started/mcp). **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](https://supabase.com/docs/guides/platform/personal-access-tokens.md#mcp-tools). ## 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](https://supabase.com/docs/guides/local-development/declarative-database-schemas). ### 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 --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](https://supabase.com/docs/guides/monitoring-and-debugging.md) 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](references/skill-feedback.md) **MUST read when** the user reports that this skill gave incorrect guidance or is missing information.